The session this one comes from. Read back as parent_session_id, and GET /v1/sessions?root= returns the whole tree under one — which is how a crew of sessions is addressed without a second noun. Recorded rather than enforced: the parent may be deleted afterwards and this still answers where the session came from. POST /v1/sessions/{id}/fork records the same relation on its own.
idle accepts input. working is running a turn. requires_action is waiting on you — see required_actions. failed is the last turn's outcome, not a dead session.
The session this one was branched from, or null when it was created directly. Recorded at creation and never cleared: the source may be edited or deleted afterwards and this still answers "where did this session come from", which is the first question asked when two sessions behave differently. The column has existed since the fork endpoint shipped; only the fork response could see it, so a session read back later had no way to say it was a branch.
Everything the session is waiting on you for. Authoritative — not a replay of events, so a caller that restarted gets the same complete answer.
Show child attributes
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"Gobare Agent API Docs","colors":{"primary":"#7a766d","light":"#f4ebdc","dark":"#111110"},"logo":{"light":"https://mintcdn.com/gobare-dev/Ph-62MdyPaY-BauC/logo/ink-dark.svg?fit=max\u0026auto=format\u0026n=Ph-62MdyPaY-BauC\u0026q=85\u0026s=b0cb33c0a05e08e6d5535259331c08c1","dark":"https://mintcdn.com/gobare-dev/Ph-62MdyPaY-BauC/logo/ink-light.svg?fit=max\u0026auto=format\u0026n=Ph-62MdyPaY-BauC\u0026q=85\u0026s=f6887af724be25489e30ec3edd44cb35"},"favicon":"https://mintcdn.com/gobare-dev/Ph-62MdyPaY-BauC/favicon.png?fit=max\u0026auto=format\u0026n=Ph-62MdyPaY-BauC\u0026q=85\u0026s=04dabf5cd88a4daa0950139b6ef9b66b","navbar":{"links":[{"href":"https://gobare.dev","label":"Gobare"},{"href":"https://github.com/MishaBear94/gobare_tools","label":"GitHub"}],"primary":{"type":"button","label":"Log in","href":"https://app.gobare.dev"}},"footer":{"socials":{"website":"https://gobare.dev","github":"https://github.com/MishaBear94/gobare_tools","x":"https://x.com/markovvxow","discord":"https://discord.gg/fTkEJQNmjg"}},"styling":{"latex":true},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"gobare-dev","hasAudioNarration":false,"actualSubdomain":"gobare-dev","customDomains":["docs.gobare.dev"],"gitSource":{"type":"github","owner":"mishabear94","repo":"gobare_docs","deployBranch":"main","contentDirectory":"","isPrivate":false,"mountPath":"","label":""},"chroma":{"latestBuiltDeploymentHistoryId":"6aba7ecdb873ba1b8696bd99","collectionId":"66c4c816-726c-4dcd-aefa-e46ddf65fb1c","liveDeploymentHistoryId":"6aba7ecdb873ba1b8696bd99","schemaVersion":"v3"},"entitlements":{"AI_CHAT":{"status":"DISABLED"},"WEB_MCP":{"status":"DISABLED"},"NARRATION":{"status":"DISABLED"}},"buildId":"6abb2f4a67be2e4d304d95ee","clientVersion":"0.0.4044","searchFilterCounts":[{"language":"default","tag":"Endpoints","count":44},{"language":"default","tag":"API Reference","count":44},{"language":"default","tag":"Guides","count":14},{"language":"default","tag":"Start here","count":9},{"language":"default","tag":"Integrations","count":8},{"language":"default","tag":"Running a session","count":7},{"language":"default","tag":"About this API","count":4},{"language":"default","tag":"When things go wrong","count":3},{"language":"default","tag":"API reference","count":2},{"language":"default","tag":"Client libraries","count":2}]},"assistantConfig":{"enableAskAiButton":false,"enableStarterQuestions":false,"enableContextualStarterQuestions":false,"enableAskAiSearchBar":true},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[{"name":"kill-isr","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-mintlify-slack","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"agent-integrations-settings","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-pr-grouping","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"custom-prefix","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"analytics-v7","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"user-flows-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"no-publish-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-onboarding","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"llms-txt-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving-live","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"stripTemperatureMiddleware","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"support-platform-pylon-zendesk","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"snapshot-serving","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"instant-rollback","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications-server","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"granular-notifications","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automations-fable","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fixed-ai-action-pricing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"automation-resolve-merge-conflict","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"scoped-publishing","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"mintql","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"page-level-analytics","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"editor-version-history-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-page-v2","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"full-page-search","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workspace-projects","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"assistant-v5","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"byok-sep-25","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"fork-pr-previews","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"revalidation-jwt","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"vite-origin","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"billing-updated-9-15","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-sso-scim","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"hobby-abuse-scan","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"dashboard-inbox","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-signup","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"turbopuffer-dual-write","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"workos-enabled","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"approve-review-flow","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false},{"name":"sso-setup-deadline-banner","enabled":true,"variant":{"name":"disabled","enabled":false,"feature_enabled":true},"impressionData":false}],"googleFontsInlined":false},"customCss":[],"page":{"pagePath":"api-reference/create-a-session","slug":"/api-reference/create-a-session","pageMetadata":{"title":"Create a session","description":"Create a session, optionally with an opening message.","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/sessions","href":"/api-reference/create-a-session","autogeneratedByOpenApi":true},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"Create a session, optionally with an opening message.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){return _jsx(_Fragment,{})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"title":"Create a session","description":"Create a session, optionally with an opening message.","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/sessions","href":"/api-reference/create-a-session","autogeneratedByOpenApi":true}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[],"codeExamples":{}},"jsLinks":[],"openApiReferenceData":{"operation":{"summary":"Create a session","description":"Create a session, optionally with an opening message.","operationId":"post_sessions","security":["242a9625-d6ba-4af3-8111-acc08637092c"],"parameters":["d4641bf3-314f-4dee-a347-fde249fa65c0"],"x-required-scope":"sessions:write","requestBody":"68846f6c-e678-4daf-8296-e5bede415655","responses":{"201":"f7458674-08d0-4bc2-b610-00c2a54950cc","400":"20b1d6b6-45b0-4c0f-9c1d-08fa8d9ee31f","401":"3cc3c041-f631-4cdb-900d-268c72dd3d6e","403":"7de78b03-fc49-48ab-85a1-811516feb90d","404":"2118f72d-6099-4bf6-9884-be7cfbf278ea","409":"09275408-d9c2-4341-a4b2-731ccb900e5c","429":"b36511bb-32ac-4519-bb3f-c7538fe5db1e","500":"ae2e7af9-a313-49d8-86c2-4ac113336740"},"method":"post","type":"path","servers":["4214d7e8-ac0f-452f-9246-001c2ec9e7f9"],"path":"/v1/sessions","baseUrlOptions":["https://api.{domain}"],"title":"Create a session","codeSamples":[],"requiredOnlyExamples":false,"requestExampleType":"generated","responseExampleType":"generated"},"dependencies":{"parameters":{"d4641bf3-314f-4dee-a347-fde249fa65c0":{"name":"Idempotency-Key","in":"header","required":false,"schema":{"type":"string","maxLength":255,"isRequired":false,"description":"Retrying with the same key replays the first answer instead of acting again.","uniqueKey":"","typeLabel":"string"},"description":"Retrying with the same key replays the first answer instead of acting again."}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","example":{"agent":{"model":"MiniMax-M3"},"input":"Write /workspace/outputs/report.md about this repo."},"description":"Everything optional. A session with only a model is a complete session.","properties":{"agent":{"type":"object","description":"What runs, and how freely. Omit every field and the organization's default connection runs it.","properties":{"id":{"type":"string","description":"An agent to inherit from. Per-field overrides still apply.","uniqueKey":"agent.id","typeLabel":"string"},"model":{"type":"string","description":"Must be one the chosen credential runs.","uniqueKey":"agent.model","typeLabel":"string"},"model_credential_id":{"type":"string","description":"Omit to use the organization's default.","uniqueKey":"agent.model_credential_id","typeLabel":"string"},"instructions":{"oneOf":[{"type":"string","maxLength":32000,"description":"Standing instructions for every turn. `null` clears an inherited one.","uniqueKey":"agent.instructions.oneOf.0","typeLabel":"string"},{"type":"null","maxLength":32000,"description":"Standing instructions for every turn. `null` clears an inherited one.","uniqueKey":"agent.instructions.oneOf.1","typeLabel":"null"}],"uniqueKey":"agent.instructions","typeLabel":"string | null"},"approval_mode":{"type":"string","enum":["auto","per_step","read_only","plan"],"description":"How much the agent may do without asking.","uniqueKey":"agent.approval_mode","typeLabel":"enum\u003cstring>"},"permission_rules":{"type":"array","items":{"type":"object","uniqueKey":"agent.permission_rules.items.[INDEX]","typeLabel":"object"},"description":"Path rules evaluated before a write.","uniqueKey":"agent.permission_rules","typeLabel":"object[]"},"tools":{"type":"array","items":{"type":"object","description":"One tool. `type` decides which shape applies; the fields of another are refused rather than ignored. `function` and `mcp` need a `name`; the sandbox's own networked tools are named by their `type` alone and take no other field. Naming any of the latter narrows the session to exactly the ones listed — it cannot enable one this deployment has turned off, and an empty list is a session with no way out to the network.","required":["type"],"properties":{"type":{"type":"string","enum":["function","mcp","web_search","web_fetch","image_search","browse","browser_act","screenshot"],"isRequired":true,"uniqueKey":"agent.tools.items.[INDEX].type","typeLabel":"enum\u003cstring>"},"name":{"type":"string","description":"`function` and `mcp` only, and required for both. What the agent calls it.","uniqueKey":"agent.tools.items.[INDEX].name","typeLabel":"string"},"description":{"type":"string","description":"`function` only. Read by the model to decide when to call it.","uniqueKey":"agent.tools.items.[INDEX].description","typeLabel":"string"},"parameters":{"type":"object","description":"`function` only. JSON Schema for the arguments.","uniqueKey":"agent.tools.items.[INDEX].parameters","typeLabel":"object"},"timeout_seconds":{"type":"integer","description":"`function` only. How long a required action may stay unanswered.","uniqueKey":"agent.tools.items.[INDEX].timeout_seconds","typeLabel":"integer"},"url":{"type":"string","description":"`mcp` only. http or https endpoint of the server.","uniqueKey":"agent.tools.items.[INDEX].url","typeLabel":"string"},"command":{"type":"string","description":"`mcp` only. A server started inside the workspace instead of reached over the network.","uniqueKey":"agent.tools.items.[INDEX].command","typeLabel":"string"},"args":{"type":"array","items":{"type":"string","uniqueKey":"agent.tools.items.[INDEX].args.items.[INDEX]","typeLabel":"string"},"description":"`mcp` only. Arguments for `command`.","uniqueKey":"agent.tools.items.[INDEX].args","typeLabel":"string[]"},"allowed_tools":{"type":"array","items":{"type":"string","uniqueKey":"agent.tools.items.[INDEX].allowed_tools.items.[INDEX]","typeLabel":"string"},"description":"`mcp` only. Narrow the server to these tool names.","uniqueKey":"agent.tools.items.[INDEX].allowed_tools","typeLabel":"string[]"},"required":{"type":"boolean","description":"`mcp` only. `true` fails the session loudly when the server will not connect; `false` lets the turn continue with fewer tools and an `mcp.unavailable` event. Must be a boolean — a string is refused rather than read as false.","uniqueKey":"agent.tools.items.[INDEX].required","typeLabel":"boolean"},"authorization":{"type":"string","description":"`mcp` only. Sent to the server, never returned; a read-back names it under `redacted`.","uniqueKey":"agent.tools.items.[INDEX].authorization","typeLabel":"string"},"headers":{"type":"object","additionalProperties":{"type":"string","uniqueKey":"agent.tools.items.[INDEX].headers.additionalProperties","typeLabel":"string"},"description":"`mcp` only. Also withheld from a read-back.","uniqueKey":"agent.tools.items.[INDEX].headers","typeLabel":"object"}},"uniqueKey":"agent.tools.items.[INDEX]","typeLabel":"object"},"description":"What the agent may reach outside the workspace: your own functions, MCP servers, and which built-ins. Everything inside the workspace — shell, files, git — is always there and is not configured here.","uniqueKey":"agent.tools","typeLabel":"object[]"},"text":{"type":"object","description":"Shaping the final message: how much it says, and whether it must conform to a JSON Schema.","properties":{"verbosity":{"type":"string","enum":["low","medium","high"],"description":"How much the agent says when it is done.","uniqueKey":"agent.text.verbosity","typeLabel":"enum\u003cstring>"},"format":{"type":"object","description":"Asked for, not enforced — see design-decisions.","properties":{"type":{"type":"string","const":"json_schema","uniqueKey":"agent.text.format.type","typeLabel":"string"},"schema":{"type":"object","description":"JSON Schema the final message should conform to.","uniqueKey":"agent.text.format.schema","typeLabel":"object"}},"uniqueKey":"agent.text.format","typeLabel":"object"}},"uniqueKey":"agent.text","typeLabel":"object"}},"uniqueKey":"agent","typeLabel":"object"},"environment":{"type":"object","description":"What the workspace starts with.","properties":{"template_id":{"type":"string","description":"Deprecated name for an agent id.","uniqueKey":"environment.template_id","typeLabel":"string"},"profiles":{"type":"array","items":{"type":"string","uniqueKey":"environment.profiles.items.[INDEX]","typeLabel":"string"},"description":"Environment-variable group ids. GET /v1/environment-profiles lists them.","uniqueKey":"environment.profiles","typeLabel":"string[]"},"repo":{"type":"string","description":"`owner/name`. A URL is refused; the branch is reported by the clone, not chosen.","uniqueKey":"environment.repo","typeLabel":"string"},"files":{"type":"array","description":"Files to place in the workspace before the first turn.","items":{"type":"object","description":"One file, inline. There is no Files API to reference and we do not fetch URLs on your behalf; for a large input use `environment.repo`.","required":["path","data"],"properties":{"path":{"type":"string","description":"Where in the workspace to write it. Confined to the workspace directory.","isRequired":true,"uniqueKey":"environment.files.items.[INDEX].path","typeLabel":"string"},"data":{"type":"string","description":"The file's bytes, base64. Always base64, including for text — one encoding to get right rather than two.","isRequired":true,"uniqueKey":"environment.files.items.[INDEX].data","typeLabel":"string"},"type":{"type":"string","const":"inline","description":"Optional, and `inline` is the only value. Named rather than defaulted: a caller sending `file_id` has a file we cannot reach, and treating it as inline would hand them an empty workspace with no reason why.","uniqueKey":"environment.files.items.[INDEX].type","typeLabel":"string"}},"uniqueKey":"environment.files.items.[INDEX]","typeLabel":"object"},"uniqueKey":"environment.files","typeLabel":"object[]"}},"uniqueKey":"environment","typeLabel":"object"},"parent_session_id":{"type":"string","description":"The session this one comes from. Read back as `parent_session_id`, and `GET /v1/sessions?root=` returns the whole tree under one — which is how a crew of sessions is addressed without a second noun. Recorded rather than enforced: the parent may be deleted afterwards and this still answers where the session came from. `POST /v1/sessions/{id}/fork` records the same relation on its own.","uniqueKey":"parent_session_id","typeLabel":"string"},"metadata":{"type":"object","additionalProperties":{"type":"string","uniqueKey":"metadata.additionalProperties","typeLabel":"string"},"description":"Your own labels. Returned unchanged; never interpreted.","uniqueKey":"metadata","typeLabel":"object"},"input":{"type":"string","description":"An opening message. All or nothing — if it cannot be accepted the session is not created either.","uniqueKey":"input","typeLabel":"string"},"title":{"type":"string","description":"A label for people.","uniqueKey":"title","typeLabel":"string"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"agent":{"model":"MiniMax-M3"},"input":"Write /workspace/outputs/report.md about this repo."}}},"exampleType":"generated"}},"exampleType":"generated"},"responses":{"f7458674-08d0-4bc2-b610-00c2a54950cc":{"description":"Create a session, optionally with an opening message.","content":{"application/json":{"schema":{"type":"object","required":["object","id","status","created_at","updated_at","agent","environment","preview"],"properties":{"object":{"type":"string","const":"session","description":"Always `session`. Names the shape, so a value can be identified without knowing which call returned it.","isRequired":true,"uniqueKey":"object","typeLabel":"string"},"id":{"type":"string","description":"Ours, not yours. Use `metadata` to carry your own identifier.","isRequired":true,"uniqueKey":"id","typeLabel":"string"},"status":{"type":"string","enum":["idle","working","requires_action","failed"],"description":"`idle` accepts input. `working` is running a turn. `requires_action` is waiting on you — see `required_actions`. `failed` is the last turn's outcome, not a dead session.","isRequired":true,"uniqueKey":"status","typeLabel":"enum\u003cstring>"},"created_at":{"type":"integer","description":"Unix milliseconds.","isRequired":true,"uniqueKey":"created_at","typeLabel":"integer"},"updated_at":{"type":"integer","description":"Unix milliseconds. Moves on any change, including the workspace waking.","isRequired":true,"uniqueKey":"updated_at","typeLabel":"integer"},"agent":{"type":"object","description":"What is running, and how freely.","properties":{"id":{"oneOf":[{"type":"string","description":"The agent template this session was created from, or null when it was configured inline. Still here after that template is deleted — it is history, not a live reference, which is what makes it usable for answering \"where did this session's settings come from\" long after the fact. The response has carried it since the field existed; it was simply never described here.","uniqueKey":"agent.id.oneOf.0","typeLabel":"string"},{"type":"null","description":"The agent template this session was created from, or null when it was configured inline. Still here after that template is deleted — it is history, not a live reference, which is what makes it usable for answering \"where did this session's settings come from\" long after the fact. The response has carried it since the field existed; it was simply never described here.","uniqueKey":"agent.id.oneOf.1","typeLabel":"null"}],"uniqueKey":"agent.id","typeLabel":"string | null"},"model":{"oneOf":[{"type":"string","description":"The model this session is bound to. Fixed at creation.","uniqueKey":"agent.model.oneOf.0","typeLabel":"string"},{"type":"null","description":"The model this session is bound to. Fixed at creation.","uniqueKey":"agent.model.oneOf.1","typeLabel":"null"}],"uniqueKey":"agent.model","typeLabel":"string | null"},"model_credential_id":{"oneOf":[{"type":"string","description":"The connection it runs on. `GET /v1/model-credentials` lists them.","uniqueKey":"agent.model_credential_id.oneOf.0","typeLabel":"string"},{"type":"null","description":"The connection it runs on. `GET /v1/model-credentials` lists them.","uniqueKey":"agent.model_credential_id.oneOf.1","typeLabel":"null"}],"uniqueKey":"agent.model_credential_id","typeLabel":"string | null"},"approval_mode":{"oneOf":[{"type":"string","description":"How much the agent may do without asking.","uniqueKey":"agent.approval_mode.oneOf.0","typeLabel":"string"},{"type":"null","description":"How much the agent may do without asking.","uniqueKey":"agent.approval_mode.oneOf.1","typeLabel":"null"}],"uniqueKey":"agent.approval_mode","typeLabel":"string | null"},"instructions":{"oneOf":[{"type":"string","maxLength":32000,"uniqueKey":"agent.instructions.oneOf.0","typeLabel":"string"},{"type":"null","maxLength":32000,"uniqueKey":"agent.instructions.oneOf.1","typeLabel":"null"}],"uniqueKey":"agent.instructions","typeLabel":"string | null"},"permission_rules":{"type":"array","items":{"type":"object","uniqueKey":"agent.permission_rules.items.[INDEX]","typeLabel":"object"},"uniqueKey":"agent.permission_rules","typeLabel":"object[]"},"tools":{"type":"array","items":{"type":"object","uniqueKey":"agent.tools.items.[INDEX]","typeLabel":"object"},"description":"What this session can call, as you configured it, with any secrets removed. On the single-session read only — a page of sessions does not carry it.","uniqueKey":"agent.tools","typeLabel":"object[]"}},"isRequired":true,"uniqueKey":"agent","typeLabel":"object"},"environment":{"type":"object","description":"The workspace: its state, where the agent works, and the repository bound to it.","properties":{"type":{"type":"string","const":"sandbox","uniqueKey":"environment.type","typeLabel":"string"},"state":{"type":"string","enum":["unknown","running","paused","destroyed","recovering","recovery_failed"],"description":"Where the workspace is. `unknown` until it first reports — a session is created before its sandbox exists, so this is what you see immediately after POST /v1/sessions. `running` is usable; `paused` is idle and woken by the next thing you send; `destroyed` is reclaimed and will be rebuilt on demand; `recovering` and `recovery_failed` are a rebuild in progress and one that gave up. A value outside this set is reported as null rather than passed through.","uniqueKey":"environment.state","typeLabel":"enum\u003cstring>"},"workspace_directory":{"type":"string","uniqueKey":"environment.workspace_directory","typeLabel":"string"},"repo":{"oneOf":[{"type":"object","description":"The repository bound to this session, once one is. Null when none was asked for.","properties":{"full_name":{"type":"string","description":"owner/name, as given.","uniqueKey":"environment.repo.oneOf.0.full_name","typeLabel":"string"},"branch":{"oneOf":[{"type":"string","description":"Reported by the clone, not chosen. Null until the workspace comes up.","uniqueKey":"environment.repo.oneOf.0.branch.oneOf.0","typeLabel":"string"},{"type":"null","description":"Reported by the clone, not chosen. Null until the workspace comes up.","uniqueKey":"environment.repo.oneOf.0.branch.oneOf.1","typeLabel":"null"}],"uniqueKey":"environment.repo.oneOf.0.branch","typeLabel":"string | null"},"clone_error":{"oneOf":[{"type":"string","description":"Why the clone did not happen, when it did not.","uniqueKey":"environment.repo.oneOf.0.clone_error.oneOf.0","typeLabel":"string"},{"type":"null","description":"Why the clone did not happen, when it did not.","uniqueKey":"environment.repo.oneOf.0.clone_error.oneOf.1","typeLabel":"null"}],"uniqueKey":"environment.repo.oneOf.0.clone_error","typeLabel":"string | null"}},"uniqueKey":"environment.repo.oneOf.0","typeLabel":"object"},{"type":"null","description":"The repository bound to this session, once one is. Null when none was asked for.","properties":{"full_name":{"type":"string","description":"owner/name, as given."},"branch":{"oneOf":[{"type":"string","description":"Reported by the clone, not chosen. Null until the workspace comes up."},{"type":"null","description":"Reported by the clone, not chosen. Null until the workspace comes up."}]},"clone_error":{"oneOf":[{"type":"string","description":"Why the clone did not happen, when it did not."},{"type":"null","description":"Why the clone did not happen, when it did not."}]}},"uniqueKey":"environment.repo.oneOf.1","typeLabel":"null"}],"uniqueKey":"environment.repo","typeLabel":"object | null"}},"isRequired":true,"uniqueKey":"environment","typeLabel":"object"},"preview":{"type":"object","description":"Addresses for whatever the agent is serving. See preview.md.","properties":{"url":{"oneOf":[{"type":"string","uniqueKey":"preview.url.oneOf.0","typeLabel":"string"},{"type":"null","uniqueKey":"preview.url.oneOf.1","typeLabel":"null"}],"uniqueKey":"preview.url","typeLabel":"string | null"},"port":{"oneOf":[{"type":"integer","uniqueKey":"preview.port.oneOf.0","typeLabel":"integer"},{"type":"null","uniqueKey":"preview.port.oneOf.1","typeLabel":"null"}],"uniqueKey":"preview.port","typeLabel":"integer | null"},"published_url":{"oneOf":[{"type":"string","uniqueKey":"preview.published_url.oneOf.0","typeLabel":"string"},{"type":"null","uniqueKey":"preview.published_url.oneOf.1","typeLabel":"null"}],"uniqueKey":"preview.published_url","typeLabel":"string | null"}},"isRequired":true,"uniqueKey":"preview","typeLabel":"object"},"title":{"oneOf":[{"type":"string","description":"A label for people. Set it yourself; nothing derives one.","uniqueKey":"title.oneOf.0","typeLabel":"string"},{"type":"null","description":"A label for people. Set it yourself; nothing derives one.","uniqueKey":"title.oneOf.1","typeLabel":"null"}],"uniqueKey":"title","typeLabel":"string | null"},"source":{"oneOf":[{"type":"string","enum":["api","console","cli",null],"description":"Which door created this session. Null on sessions predating the field.","uniqueKey":"source.oneOf.0","typeLabel":"enum\u003cstring>"},{"type":"null","enum":["api","console","cli",null],"description":"Which door created this session. Null on sessions predating the field.","uniqueKey":"source.oneOf.1","typeLabel":"null"}],"uniqueKey":"source","typeLabel":"enum\u003cstring> | null"},"created_by_token":{"oneOf":[{"type":"string","description":"The id of the access token that created it — never its secret.","uniqueKey":"created_by_token.oneOf.0","typeLabel":"string"},{"type":"null","description":"The id of the access token that created it — never its secret.","uniqueKey":"created_by_token.oneOf.1","typeLabel":"null"}],"uniqueKey":"created_by_token","typeLabel":"string | null"},"parent_session_id":{"oneOf":[{"type":"string","description":"The session this one was branched from, or `null` when it was created directly. Recorded at creation and never cleared: the source may be edited or deleted afterwards and this still answers \"where did this session come from\", which is the first question asked when two sessions behave differently. The column has existed since the fork endpoint shipped; only the fork response could see it, so a session read back later had no way to say it was a branch.","uniqueKey":"parent_session_id.oneOf.0","typeLabel":"string"},{"type":"null","description":"The session this one was branched from, or `null` when it was created directly. Recorded at creation and never cleared: the source may be edited or deleted afterwards and this still answers \"where did this session come from\", which is the first question asked when two sessions behave differently. The column has existed since the fork endpoint shipped; only the fork response could see it, so a session read back later had no way to say it was a branch.","uniqueKey":"parent_session_id.oneOf.1","typeLabel":"null"}],"uniqueKey":"parent_session_id","typeLabel":"string | null"},"required_actions":{"type":"array","description":"Everything the session is waiting on you for. Authoritative — not a replay of events, so a caller that restarted gets the same complete answer.","items":{"type":"object","required":["type","turn_id","call_id"],"description":"Something this session is waiting for. Copy turn_id and call_id into the result you submit.","properties":{"type":{"type":"string","enum":["function_call","approval","question"],"description":"What is being asked of you. `function_call` you answer through the API; `approval` and `question` are answered by a person in the Console.","isRequired":true,"uniqueKey":"required_actions.items.[INDEX].type","typeLabel":"enum\u003cstring>"},"turn_id":{"type":"string","description":"Copy this back when answering.","isRequired":true,"uniqueKey":"required_actions.items.[INDEX].turn_id","typeLabel":"string"},"call_id":{"type":"string","description":"Copy this back when answering. It identifies which call the result is for.","isRequired":true,"uniqueKey":"required_actions.items.[INDEX].call_id","typeLabel":"string"},"name":{"oneOf":[{"type":"string","description":"The function the agent wants to call, as you declared it.","uniqueKey":"required_actions.items.[INDEX].name.oneOf.0","typeLabel":"string"},{"type":"null","description":"The function the agent wants to call, as you declared it.","uniqueKey":"required_actions.items.[INDEX].name.oneOf.1","typeLabel":"null"}],"uniqueKey":"required_actions.items.[INDEX].name","typeLabel":"string | null"},"arguments":{"description":"What it wants to call the function with. Shaped by your own parameter schema.","uniqueKey":"required_actions.items.[INDEX].arguments","typeLabel":"any"},"created_at":{"type":"integer","description":"Unix milliseconds, when the agent asked.","uniqueKey":"required_actions.items.[INDEX].created_at","typeLabel":"integer"},"expires_at":{"oneOf":[{"type":"integer","description":"Unix milliseconds, when this stops being waited for — set from the tool's own `timeout_seconds`. Null, the default, means it waits indefinitely. Past this the call is answered as failed and the turn continues; the turn itself does not fail.","uniqueKey":"required_actions.items.[INDEX].expires_at.oneOf.0","typeLabel":"integer"},{"type":"null","description":"Unix milliseconds, when this stops being waited for — set from the tool's own `timeout_seconds`. Null, the default, means it waits indefinitely. Past this the call is answered as failed and the turn continues; the turn itself does not fail.","uniqueKey":"required_actions.items.[INDEX].expires_at.oneOf.1","typeLabel":"null"}],"uniqueKey":"required_actions.items.[INDEX].expires_at","typeLabel":"integer | null"}},"uniqueKey":"required_actions.items.[INDEX]","typeLabel":"object"},"uniqueKey":"required_actions","typeLabel":"object[]"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"object":"session","id":"\u003cstring>","status":"idle","created_at":123,"updated_at":123,"agent":{"id":"\u003cstring>","model":"\u003cstring>","model_credential_id":"\u003cstring>","approval_mode":"\u003cstring>","instructions":"\u003cstring>","permission_rules":[{}],"tools":[{}]},"environment":{"type":"sandbox","state":"unknown","workspace_directory":"\u003cstring>","repo":{"full_name":"\u003cstring>","branch":"\u003cstring>","clone_error":"\u003cstring>"}},"preview":{"url":"\u003cstring>","port":123,"published_url":"\u003cstring>"},"title":"\u003cstring>","source":"api","created_by_token":"\u003cstring>","parent_session_id":"\u003cstring>","required_actions":[{"type":"function_call","turn_id":"\u003cstring>","call_id":"\u003cstring>","name":"\u003cstring>","arguments":"\u003cunknown>","created_at":123,"expires_at":123}]}}},"exampleType":"generated"}},"exampleType":"generated"},"20b1d6b6-45b0-4c0f-9c1d-08fa8d9ee31f":{"description":"`invalid_request`. A field this endpoint does not read, a field of the wrong shape, a query parameter it does not take, or a body past the size ceiling. Refused rather than ignored: a setting you believe you made is one we really made.","content":{"application/json":{"schema":{"type":"object","required":["error"],"description":"Every refusal this API makes, in one shape.","properties":{"error":{"description":"Always present on a failure, and the only thing present.","type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_request","authentication_error","permission_denied","not_found","method_not_allowed","conflict","queue_full","rate_limit_exceeded","project_limit_exceeded","context_length_exceeded","provider_error","provider_unauthorized","sandbox_error","sandbox_unavailable","directory_unavailable","workspace_recovery_failed","bridge_incompatible","internal_error"],"isRequired":true,"uniqueKey":"error.code","typeLabel":"enum\u003cstring>"},"message":{"type":"string","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"request_id":{"type":"string","description":"Also on the x-request-id header. Quote it when reporting a problem.","isRequired":true,"uniqueKey":"error.request_id","typeLabel":"string"}},"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"invalid_request","message":"\u003cstring>","request_id":"\u003cstring>"}}}},"exampleType":"generated"}},"exampleType":"generated"},"3cc3c041-f631-4cdb-900d-268c72dd3d6e":{"description":"The access token is missing, unrecognised, expired or revoked.","content":{"application/json":{"schema":{"type":"object","required":["error"],"description":"Every refusal this API makes, in one shape.","properties":{"error":{"description":"Always present on a failure, and the only thing present.","type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_request","authentication_error","permission_denied","not_found","method_not_allowed","conflict","queue_full","rate_limit_exceeded","project_limit_exceeded","context_length_exceeded","provider_error","provider_unauthorized","sandbox_error","sandbox_unavailable","directory_unavailable","workspace_recovery_failed","bridge_incompatible","internal_error"],"isRequired":true,"uniqueKey":"error.code","typeLabel":"enum\u003cstring>"},"message":{"type":"string","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"request_id":{"type":"string","description":"Also on the x-request-id header. Quote it when reporting a problem.","isRequired":true,"uniqueKey":"error.request_id","typeLabel":"string"}},"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"invalid_request","message":"\u003cstring>","request_id":"\u003cstring>"}}}},"exampleType":"generated"}},"exampleType":"generated"},"7de78b03-fc49-48ab-85a1-811516feb90d":{"description":"The token is valid but may not perform this call. The message names the scope it wanted.","content":{"application/json":{"schema":{"type":"object","required":["error"],"description":"Every refusal this API makes, in one shape.","properties":{"error":{"description":"Always present on a failure, and the only thing present.","type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_request","authentication_error","permission_denied","not_found","method_not_allowed","conflict","queue_full","rate_limit_exceeded","project_limit_exceeded","context_length_exceeded","provider_error","provider_unauthorized","sandbox_error","sandbox_unavailable","directory_unavailable","workspace_recovery_failed","bridge_incompatible","internal_error"],"isRequired":true,"uniqueKey":"error.code","typeLabel":"enum\u003cstring>"},"message":{"type":"string","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"request_id":{"type":"string","description":"Also on the x-request-id header. Quote it when reporting a problem.","isRequired":true,"uniqueKey":"error.request_id","typeLabel":"string"}},"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"invalid_request","message":"\u003cstring>","request_id":"\u003cstring>"}}}},"exampleType":"generated"}},"exampleType":"generated"},"2118f72d-6099-4bf6-9884-be7cfbf278ea":{"description":"No such endpoint, or the public API is not enabled on this deployment.","content":{"application/json":{"schema":{"type":"object","required":["error"],"description":"Every refusal this API makes, in one shape.","properties":{"error":{"description":"Always present on a failure, and the only thing present.","type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_request","authentication_error","permission_denied","not_found","method_not_allowed","conflict","queue_full","rate_limit_exceeded","project_limit_exceeded","context_length_exceeded","provider_error","provider_unauthorized","sandbox_error","sandbox_unavailable","directory_unavailable","workspace_recovery_failed","bridge_incompatible","internal_error"],"isRequired":true,"uniqueKey":"error.code","typeLabel":"enum\u003cstring>"},"message":{"type":"string","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"request_id":{"type":"string","description":"Also on the x-request-id header. Quote it when reporting a problem.","isRequired":true,"uniqueKey":"error.request_id","typeLabel":"string"}},"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"invalid_request","message":"\u003cstring>","request_id":"\u003cstring>"}}}},"exampleType":"generated"}},"exampleType":"generated"},"09275408-d9c2-4341-a4b2-731ccb900e5c":{"description":"The session's state does not allow this call, or an identical request is already in flight under the same Idempotency-Key.","content":{"application/json":{"schema":{"type":"object","required":["error"],"description":"Every refusal this API makes, in one shape.","properties":{"error":{"description":"Always present on a failure, and the only thing present.","type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_request","authentication_error","permission_denied","not_found","method_not_allowed","conflict","queue_full","rate_limit_exceeded","project_limit_exceeded","context_length_exceeded","provider_error","provider_unauthorized","sandbox_error","sandbox_unavailable","directory_unavailable","workspace_recovery_failed","bridge_incompatible","internal_error"],"isRequired":true,"uniqueKey":"error.code","typeLabel":"enum\u003cstring>"},"message":{"type":"string","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"request_id":{"type":"string","description":"Also on the x-request-id header. Quote it when reporting a problem.","isRequired":true,"uniqueKey":"error.request_id","typeLabel":"string"}},"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"invalid_request","message":"\u003cstring>","request_id":"\u003cstring>"}}}},"exampleType":"generated"}},"exampleType":"generated"},"b36511bb-32ac-4519-bb3f-c7538fe5db1e":{"description":"`rate_limit_exceeded` — the token is past its allowance for this bucket; honour `Retry-After`. Or `queue_full` — too many messages are already waiting behind the current turn. Branch on `code`.","content":{"application/json":{"schema":{"type":"object","required":["error"],"description":"Every refusal this API makes, in one shape.","properties":{"error":{"description":"Always present on a failure, and the only thing present.","type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_request","authentication_error","permission_denied","not_found","method_not_allowed","conflict","queue_full","rate_limit_exceeded","project_limit_exceeded","context_length_exceeded","provider_error","provider_unauthorized","sandbox_error","sandbox_unavailable","directory_unavailable","workspace_recovery_failed","bridge_incompatible","internal_error"],"isRequired":true,"uniqueKey":"error.code","typeLabel":"enum\u003cstring>"},"message":{"type":"string","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"request_id":{"type":"string","description":"Also on the x-request-id header. Quote it when reporting a problem.","isRequired":true,"uniqueKey":"error.request_id","typeLabel":"string"}},"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"invalid_request","message":"\u003cstring>","request_id":"\u003cstring>"}}}},"exampleType":"generated"}},"exampleType":"generated"},"ae2e7af9-a313-49d8-86c2-4ac113336740":{"description":"An unexpected error. Quote the request id.","content":{"application/json":{"schema":{"type":"object","required":["error"],"description":"Every refusal this API makes, in one shape.","properties":{"error":{"description":"Always present on a failure, and the only thing present.","type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_request","authentication_error","permission_denied","not_found","method_not_allowed","conflict","queue_full","rate_limit_exceeded","project_limit_exceeded","context_length_exceeded","provider_error","provider_unauthorized","sandbox_error","sandbox_unavailable","directory_unavailable","workspace_recovery_failed","bridge_incompatible","internal_error"],"isRequired":true,"uniqueKey":"error.code","typeLabel":"enum\u003cstring>"},"message":{"type":"string","isRequired":true,"uniqueKey":"error.message","typeLabel":"string"},"request_id":{"type":"string","description":"Also on the x-request-id header. Quote it when reporting a problem.","isRequired":true,"uniqueKey":"error.request_id","typeLabel":"string"}},"isRequired":true,"uniqueKey":"error","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"error":{"code":"invalid_request","message":"\u003cstring>","request_id":"\u003cstring>"}}}},"exampleType":"generated"}},"exampleType":"generated"}},"security":{"242a9625-d6ba-4af3-8111-acc08637092c":{"accessToken":{"type":"http","scheme":"bearer","description":"A `gbr_pat_` access token. Scopes are recorded on the token when it is minted.","scopes":[]}}},"servers":{"4214d7e8-ac0f-452f-9246-001c2ec9e7f9":{"url":"https://api.{domain}","variables":{"domain":{"default":"gobare.dev"}}}},"processedSecurityOptions":[{"schemes":[{"scheme":{"type":"http","scheme":"bearer","description":"A `gbr_pat_` access token. Scopes are recorded on the token when it is minted.","scopes":[]},"schema":{"title":"Bearer Auth","type":"string","isRequired":true,"description":"A `gbr_pat_` access token. Scopes are recorded on the token when it is minted.","format":"bearer","typeLabel":"string\u003cbearer>","deprecated":false},"schemeName":"accessToken","name":"Authorization"}],"title":"accessToken"}]},"originalFileLocation":"openapi.json"},"subdomain":"gobare-dev","siteName":"Gobare Agent API Docs","title":"Create a session - Gobare Agent API Docs","navMaps":{"firstHrefInVersion":{},"firstHrefInLanguage":{}},"lastModified":"2026-09-25T10:12:33.062Z","originalFileLocation":"api-reference/create-a-session.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Create a session, optionally with an opening message.\">\u003cmeta data-mint-head name=\"application-name\" content=\"Gobare Agent API Docs\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/gobare-dev/DajiJMR4Tez08wMz/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/gobare-dev/DajiJMR4Tez08wMz/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/gobare-dev/DajiJMR4Tez08wMz/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/gobare-dev/DajiJMR4Tez08wMz/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/gobare-dev/DajiJMR4Tez08wMz/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/gobare-dev/DajiJMR4Tez08wMz/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/gobare-dev/DajiJMR4Tez08wMz/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/gobare-dev/DajiJMR4Tez08wMz/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/gobare-dev/DajiJMR4Tez08wMz/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Create a session - Gobare Agent API Docs\">\u003cmeta data-mint-head property=\"og:description\" content=\"Create a session, optionally with an opening message.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"Gobare Agent API Docs\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.gobare.dev/api-reference/create-a-session\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://gobare-dev.mintlify.app/_mintlify/api/og/v2?division=API+Reference\u0026amp;title=Create+a+session\u0026amp;description=Create+a+session%2C+optionally+with+an+opening+message.\u0026amp;theme=6f5c05db30b78253e714dbc4\u0026amp;signature=a6b5851d86a7b03fc7a439bd61c63da47156af6b54a236dc4bf7fe2c39bd6bbf\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Create a session - Gobare Agent API Docs\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Create a session, optionally with an opening message.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://gobare-dev.mintlify.app/_mintlify/api/og/v2?division=API+Reference\u0026amp;title=Create+a+session\u0026amp;description=Create+a+session%2C+optionally+with+an+opening+message.\u0026amp;theme=6f5c05db30b78253e714dbc4\u0026amp;signature=a6b5851d86a7b03fc7a439bd61c63da47156af6b54a236dc4bf7fe2c39bd6bbf\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/gobare-dev/DajiJMR4Tez08wMz/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"Gobare Agent API Docs\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#7a766d\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.gobare.dev/api-reference/create-a-session\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference/create-a-session.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.gobare.dev/#organization\",\"name\":\"Gobare Agent API Docs\",\"url\":\"https://docs.gobare.dev\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/gobare-dev/Ph-62MdyPaY-BauC/logo/ink-dark.svg?fit=max\u0026auto=format\u0026n=Ph-62MdyPaY-BauC\u0026q=85\u0026s=b0cb33c0a05e08e6d5535259331c08c1\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.gobare.dev#website\",\"name\":\"Gobare Agent API Docs\",\"url\":\"https://docs.gobare.dev\",\"publisher\":{\"@id\":\"https://docs.gobare.dev/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.gobare.dev/api-reference/create-a-session#webpage\",\"url\":\"https://docs.gobare.dev/api-reference/create-a-session\",\"name\":\"Create a session\",\"description\":\"Create a session, optionally with an opening message.\",\"dateModified\":\"2026-09-25T10:12:33.062Z\",\"isPartOf\":{\"@id\":\"https://docs.gobare.dev#website\"},\"breadcrumb\":{\"@id\":\"https://docs.gobare.dev/api-reference/create-a-session#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.gobare.dev/api-reference/create-a-session#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Endpoints\",\"item\":\"https://docs.gobare.dev/api-reference/check-the-access-token\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"API Reference\",\"item\":\"https://docs.gobare.dev/api-reference/check-the-access-token\"},{\"@type\":\"ListItem\",\"position\":3,\"name\":\"Create a session\",\"item\":\"https://docs.gobare.dev/api-reference/create-a-session\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.gobare.dev/api-reference/create-a-session#apireference\",\"headline\":\"Create a session\",\"name\":\"Create a session\",\"description\":\"Create a session, optionally with an opening message.\",\"url\":\"https://docs.gobare.dev/api-reference/create-a-session\",\"mainEntityOfPage\":{\"@id\":\"https://docs.gobare.dev/api-reference/create-a-session#webpage\"},\"dateModified\":\"2026-09-25T10:12:33.062Z\",\"publisher\":{\"@id\":\"https://docs.gobare.dev/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.gobare.dev#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"Gobare Agent API Docs\",\"creator\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","siteName":"Gobare Agent API Docs","nav":{"global":null,"groups":[{"group":"Start here","pages":[{"title":"Gobare Agent API","href":"/index"},{"title":"The agent is pi","href":"/pi"},{"title":"How Gobare is different","href":"/why-gobare"},{"title":"Build without writing code","href":"/without-code"},{"title":"Quickstart","href":"/quickstart"},{"title":"Production integration","href":"/production-integration"},{"title":"Model credentials: bring your own key","sidebarTitle":"Model credentials","href":"/model-credentials"},{"title":"Sessions","href":"/sessions"},{"title":"Agents","href":"/saved-agents"}]},{"group":"Running a session","pages":[{"title":"Input","href":"/input"},{"title":"Events: a resumable agent event stream","sidebarTitle":"Events","href":"/events"},{"title":"Tools: your functions, MCP servers, and a browser in the sandbox","sidebarTitle":"Tools","href":"/tools"},{"title":"Required actions","href":"/required-actions"},{"title":"Webhooks for long-running agents","sidebarTitle":"Webhooks","href":"/webhooks"},{"title":"Idempotency","href":"/idempotency"},{"title":"Preview","href":"/preview"}]},{"group":"Guides","pages":[{"title":"Guides","href":"/guides"},{"title":"Turn documents into structured JSON","href":"/guides/extracting-structured-data"},{"title":"Put an agent behind your own API","href":"/guides/an-agent-behind-your-api"},{"title":"Human-in-the-loop for agents: require approval over an API","href":"/guides/approvals-in-your-product"},{"title":"Stream the agent's progress into your UI","href":"/guides/showing-the-agents-work"},{"title":"Continue work across hours and rounds","href":"/guides/work-that-spans-hours"},{"title":"Swap model providers without changing your code","href":"/guides/switching-model-providers"},{"title":"Let several agents work on one thing","href":"/guides/agents-that-work-together"},{"title":"Keep a crew honest","href":"/guides/keep-a-crew-honest"},{"title":"Run a fleet of ticket-driven agents in parallel","href":"/guides/parallel-ticket-fleet"},{"title":"Give an agent your tracker","href":"/guides/give-an-agent-your-tracker"},{"title":"Fix a GitHub issue and open the pull request","href":"/guides/fix-a-github-issue"},{"title":"Take over the machine the agent is working on","href":"/guides/take-over-the-agents-machine"},{"title":"Publish an app and let a visitor wake it","href":"/guides/wake-a-published-app"}]},{"group":"Integrations","pages":[{"title":"Integrations","href":"/integrations/overview"},{"title":"Run a session inside a Temporal workflow","href":"/integrations/temporal"},{"title":"Give your agent framework a computer","href":"/integrations/agent-frameworks"},{"title":"Review pull requests in GitHub Actions","href":"/integrations/github-actions"},{"title":"Put an agent in a Slack thread","href":"/integrations/slack"},{"title":"Receive webhooks on Cloudflare Workers","href":"/integrations/cloudflare-workers"},{"title":"Meter usage into Stripe and Prometheus","href":"/integrations/usage-metering"},{"title":"Test a webhook handler without production","href":"/integrations/testing-webhook-handlers"}]},{"group":"Client libraries","pages":[{"title":"TypeScript client","href":"/typescript"},{"title":"Python client","href":"/python"}]},{"group":"When things go wrong","pages":[{"title":"Troubleshooting","href":"/troubleshooting"},{"title":"Errors","href":"/errors"},{"title":"Limits","href":"/limits"}]},{"group":"API reference","pages":[{"title":"Pagination","href":"/pagination"},{"title":"Objects","href":"/objects"}]},{"group":"About this API","pages":[{"title":"Changelog","href":"/changelog"},{"title":"Design decisions","href":"/design-decisions"},{"title":"The session loop","href":"/run-session"},{"title":"Build an integration","href":"/AGENTS"}]},{"group":"Endpoints","pages":[{"group":"API Reference","pages":[{"title":"Check the access token","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/health","href":"/api-reference/check-the-access-token"},{"title":"List sessions","description":"List the organization's sessions.","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/sessions","href":"/api-reference/list-sessions"},{"title":"Create a session","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/sessions","href":"/api-reference/create-a-session"},{"title":"Retrieve a session","description":"Retrieve one session.","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/sessions/{session_id}","href":"/api-reference/retrieve-a-session"},{"title":"Delete a session","deprecated":null,"version":null,"openapi":"/openapi.json delete /v1/sessions/{session_id}","href":"/api-reference/delete-a-session"},{"title":"Update a session","deprecated":null,"version":null,"openapi":"/openapi.json patch /v1/sessions/{session_id}","href":"/api-reference/update-a-session"},{"title":"List turns","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/sessions/{session_id}/turns","href":"/api-reference/list-turns"},{"title":"Retrieve a turn","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/sessions/{session_id}/turns/{turn_id}","href":"/api-reference/retrieve-a-turn"},{"title":"Stream a session's events","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/sessions/{session_id}/events","href":"/api-reference/stream-a-sessions-events"},{"title":"Send input to a session","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/sessions/{session_id}/events","href":"/api-reference/send-input-to-a-session"},{"title":"Stream every session's events","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/events","href":"/api-reference/stream-every-sessions-events"},{"title":"Retrieve sandbox usage","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/sessions/{session_id}/usage","href":"/api-reference/retrieve-sandbox-usage"},{"title":"List items","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/sessions/{session_id}/items","href":"/api-reference/list-items"},{"title":"Fork a session","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/sessions/{session_id}/fork","href":"/api-reference/fork-a-session"},{"title":"Read a session's tools","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/sessions/{session_id}/tools","href":"/api-reference/read-a-sessions-tools"},{"title":"Replace a session's tools","deprecated":null,"version":null,"openapi":"/openapi.json put /v1/sessions/{session_id}/tools","href":"/api-reference/replace-a-sessions-tools"},{"title":"List webhooks","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/webhooks","href":"/api-reference/list-webhooks"},{"title":"Create a webhook","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/webhooks","href":"/api-reference/create-a-webhook"},{"title":"Delete a webhook","deprecated":null,"version":null,"openapi":"/openapi.json delete /v1/webhooks/{webhook_id}","href":"/api-reference/delete-a-webhook"},{"title":"List artifacts","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/sessions/{session_id}/artifacts","href":"/api-reference/list-artifacts"},{"title":"Download all artifacts","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/sessions/{session_id}/artifacts/archive","href":"/api-reference/download-all-artifacts"},{"title":"Retrieve an artifact","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/sessions/{session_id}/artifacts/{artifact_id}","href":"/api-reference/retrieve-an-artifact"},{"title":"Delete an artifact","deprecated":null,"version":null,"openapi":"/openapi.json delete /v1/sessions/{session_id}/artifacts/{artifact_id}","href":"/api-reference/delete-an-artifact"},{"title":"Download an artifact","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/sessions/{session_id}/artifacts/{artifact_id}/content","href":"/api-reference/download-an-artifact"},{"title":"List workspace files","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/sessions/{session_id}/files","href":"/api-reference/list-workspace-files"},{"title":"Write workspace files","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/sessions/{session_id}/files","href":"/api-reference/write-workspace-files"},{"title":"Read a workspace file","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/sessions/{session_id}/files/content","href":"/api-reference/read-a-workspace-file"},{"title":"Refresh the workspace","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/sessions/{session_id}/files/refresh","href":"/api-reference/refresh-the-workspace"},{"title":"List agents","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/agents","href":"/api-reference/list-agents"},{"title":"Create or replace an agent","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/agents","href":"/api-reference/create-or-replace-an-agent"},{"title":"Retrieve an agent","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/agents/{agent_id}","href":"/api-reference/retrieve-an-agent"},{"title":"Delete an agent","deprecated":null,"version":null,"openapi":"/openapi.json delete /v1/agents/{agent_id}","href":"/api-reference/delete-an-agent"},{"title":"List environment templates","deprecated":true,"version":null,"openapi":"/openapi.json get /v1/environment-templates","href":"/api-reference/list-environment-templates"},{"title":"Create an environment template","deprecated":true,"version":null,"openapi":"/openapi.json post /v1/environment-templates","href":"/api-reference/create-an-environment-template"},{"title":"Retrieve an environment template","deprecated":true,"version":null,"openapi":"/openapi.json get /v1/environment-templates/{template_id}","href":"/api-reference/retrieve-an-environment-template"},{"title":"Delete an environment template","deprecated":true,"version":null,"openapi":"/openapi.json delete /v1/environment-templates/{template_id}","href":"/api-reference/delete-an-environment-template"},{"title":"List environment profiles","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/environment-profiles","href":"/api-reference/list-environment-profiles"},{"title":"List model providers","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/model-connectors","href":"/api-reference/list-model-providers"},{"title":"List model credentials","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/model-credentials","href":"/api-reference/list-model-credentials"},{"title":"Connect a model credential","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/model-credentials","href":"/api-reference/connect-a-model-credential"},{"title":"Remove a model credential","deprecated":null,"version":null,"openapi":"/openapi.json delete /v1/model-credentials/{credential_id}","href":"/api-reference/remove-a-model-credential"},{"title":"Publish a preview","deprecated":null,"version":null,"openapi":"/openapi.json post /v1/sessions/{session_id}/preview","href":"/api-reference/publish-a-preview"},{"title":"Unpublish a preview","deprecated":null,"version":null,"openapi":"/openapi.json delete /v1/sessions/{session_id}/preview","href":"/api-reference/unpublish-a-preview"},{"title":"Retrieve the OpenAPI document","deprecated":null,"version":null,"openapi":"/openapi.json get /v1/openapi.json","href":"/api-reference/retrieve-the-openapi-document"}]}]}]},"basePath":"","title":"Create a session - Gobare Agent API Docs","buildId":"dpl_DeHjVRGfFnhYQwHnfC2pjeXXv8h9","deploymentId":"dpl_DeHjVRGfFnhYQwHnfC2pjeXXv8h9","dynamics":["c2aa737661","2b790eda92","b0f84f53ff","a9bb46feb3"],"chunks":["OpenApiReferenceProvider-CS552b7R.js","utils-DDTCYAF2.js","cloneDeep-izs3Hzxb.js","_Uint8Array-BVIqJ90l.js","isObjectLike-C8vmzPEN.js","isArray-Dcu1dQ5t.js","utils-De8ttokP.js","toString-BX-iyh8G.js","isSymbol-CSH9U2Gm.js","addUniqueKeysToSchema-DrwRDvAh.js","snippetPresets-DtAN0nWx.js","style-to-object-BY3JEAdk.js","v4-DIgz8zy6.js","ApiExamples-D5rWArI6.js","isEqual-BfaiBbcl.js","usePlaygroundInputsStore-O2i12wsz.js","shallow-DV8xABTt.js","getApiPlaygroundDisplay-DBZ0B5Jx.js","CodeSnippet-BVi0tPUX.js","CodeSnippets-CqASbIwY.js","Page-m07pfKpT.js","getPastedJson-DG9vsMS8.js","icon-CXzRSCr8.js","MethodPill-BdKVtEuX.js","DuplicateIcon-CZlmBrJI.js","createIcon-biFEUKPL.js","DynamicMarkdown-B54_zNBF.js","SectionHeading-DwwHK3Pt.js","axios-vUo_bRtp.js","Markdown-DfhCTwyA.js","clsx-xpJZXxdP.js","lib-DuNMoZ05.js","lib-B8HbPgcC.js","html-void-elements-mCSPHezU.js","dist-BTZUMDnx.js","katex-YMM-FMeD.js","marked.esm-CZWythHk.js","AssistantPageLink-DqdKa2R4.js"]}