POST
/v2/agents/sessionsCreate a Harness Runtime session
Creates a Harness Runtime session from a JSON configuration reference or an environment spec supplied as YAML. For JSON, provide name and config_id; for YAML, send the environment spec with a supported YAML Content-Type. Sandbox boot continues asynchronously after the session row is allocated.
- IdempotentThe SDK sends
Idempotency-Key, so a retried request is only applied once.
openai_session_idstringoptional
OpenAI Agents API session identifier for the `codex-agentapi` adapter, typically beginning with `sess_`; omit it for other agent kinds.
resume_on_topoffbooleanoptional
Opts the session into automatic resumption when the team's prepayment balance is restored. Defaults to false when omitted; accepts only `true`, `false`, `1`, or `0`, and takes precedence over the body field when both are supplied.
X-Device-UUIDstringoptional
Optional hardware device identifier persisted on the session row for lifecycle attribution; values over 128 bytes are ignored.
For JSON, send a strict CreateSession request with name and config_id; the body is limited to 16 KiB and does not accept inline secrets. The live API also accepts raw environment specs with supported YAML content types, limited to 1 MiB.
namestringrequired
Session name, independent of the config name. Must satisfy the existing environment-spec metadata.name rules and must not be UUID-shaped.
config_idstringrequired
UUID of the environment config to load; its credentials are resolved from the secret versions pinned when the config was created.
resume_on_topoffbooleanoptional
Opt the new session in to automatic resumption when the team's prepayment balance is restored. Defaults to false. Session-scoped, not config-scoped: the referenced config never confers this, so one shared config cannot enrol every session created from it. Omit to leave the default (or to let the ?resume_on_topoff= query parameter supply it).
200Returns the allocated session record, including session identifiers, name, status, sandbox details, and session timestamps; the response may also include `config_id`. Sandbox boot continues asynchronously.
sessionobjectoptional
Session is the user-facing record of a environment session + sandbox pair.
400Returned when the manifest or config is invalid, credentials are incompatible, or a query parameter is invalid.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
401Returned when authentication fails because the credentials are invalid.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
402Returned when the team is blocked by the prepayment gate.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
403Returned when Secrets Manager denies access to a pinned credential.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
404Returned when the requested resource is not found.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
409Returned when the team has reached its active-session quota or a live session already uses the requested name.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
413Returned when the JSON body exceeds 16 KiB or the YAML body exceeds 1 MiB.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
415Returned when the request uses an unsupported content type.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
429Returned when the API rate limit has been exceeded.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
500Returned when a server error occurs.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
501Returned when the requested capability is unavailable.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
503Returned when Secrets Manager is unavailable.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
defaultThere was an unexpected error.
idstringrequired
A short identifier corresponding to the HTTP status code returned. For example, the ID for a response returning a 404 status code would be "not_found."
messagestringrequired
A message providing additional information about the error, including details to help resolve it when possible.
request_idstringoptional
Optionally, some endpoints may include a request ID that should be provided when reporting bugs or opening support tickets to help identify the issue.
Error handling
A 400 is returned for an invalid manifest or config, incompatible credentials, or an invalid query parameter; 401 indicates invalid authentication credentials; 402 indicates that the team is blocked by the prepayment gate; 403 indicates that Secrets Manager denied access to a pinned credential; 404 indicates that a resource was not found; 409 indicates that the team reached its active-session quota or a live session already uses the name; 413 indicates that the request body exceeds its size limit; 415 indicates an unsupported Content-Type; 429 indicates that the API rate limit was exceeded; 500 indicates a server error; 501 indicates that the requested capability is unavailable; and 503 indicates that Secrets Manager is unavailable. For JSON requests, name must be 1–64 characters and must not be UUID-shaped, and config_id must be a UUID; the JSON body limit is 16 KiB, while YAML bodies are limited to 1 MiB. The resume_on_topoff query parameter must be exactly true, false, 1, or 0; when both the query parameter and body field are present, the query parameter takes precedence.