InspectCreate session
Create a new Inspect session with an initial prompt. Accepts either `application/json` or `multipart/form-data`. Use multipart when you need to upload file attachments alongside the prompt; put the JSON request in the `data` field. Supports an `Idempotency-Key` request header. When the same key is sent twice from the same API key, the second call returns the originally-created session (HTTP 200) instead of creating a new one. Keys are scoped per API key user and remain valid until the originally-created session is archived; a same-key request after archive starts a fresh session.
Create a new Inspect session with an initial prompt. Accepts either application/json or multipart/form-data. Use multipart when you need to upload file attachments alongside the prompt; put the JSON request in the data field.
Supports an Idempotency-Key request header. When the same key is sent twice from the same API key, the second call returns the originally-created session (HTTP 200) instead of creating a new one. Keys are scoped per API key user and remain valid until the originally-created session is archived; a same-key request after archive starts a fresh session.
bearerAuthAuthorizationBearer <token>API key authentication. Use your API key as the bearer token.
Idempotency-Key?stringOptional client-supplied key for safe retries. A same-key retry from the same API key user returns the originally-created session (HTTP 200) instead of creating a duplicate. Trimmed; blank keys are ignored, otherwise 8 to 255 characters. Idempotency is keyed per API key user.
length <= 255- body
review_buddy_reviewers?array<>Optional Review agent reviewers. Each model must be available to the caller and support the requested reasoning effort.
repository*stringThe repository to create the session for. Use "auto" to infer the best repository from the prompt.
1 <= lengthprompt?stringThe initial prompt for the session. At least one of prompt, attachments, or agent_context is required.
title?stringOptional title for the session. When omitted, Inspect generates one from the creation request.
no_reply?booleanIf true, stores the prompt and dispatches the runner silently without posting an assistant reply back into the session timeline.
falsemodel?||Optional model ID or shorthand alias. An explicit model takes precedence over custom-agent and saved-default models; leave unspecified to use the normal default selection. Use GET /api/public/v1/models for model IDs and aliases.
variant?Models.ModelVariant"low""medium""high""xhigh""max""minimal""none"service_tier?Sessions.ModelServiceTierOptional model service tier. Supported values depend on the selected model; unsupported combinations return 400.
"default""auto""flex""priority"agent?stringDeprecatedDeprecated. This field is ignored for session APIs and only kept for backwards compatibility.
enabled_skill_ids?array<>Optional list of skill IDs to enable for this session in addition to those configured on the caller's user settings, custom agent, or referenced via slash commands in the prompt. Unknown skill IDs are ignored.
base_branch?stringOptional base branch, defaults to the repository's default branch. If provided, Inspect normalizes common Git prefixes and verifies the branch exists on GitHub before creating the session.
base_commit?stringBenchmark mode only (SWE-bench agent). Pins the session to a per-session Code Storage fork of the repository at this commit SHA: full real history up to the commit, no forward history, and no GitHub remote. Required (non-blank) for the SWE-bench agent; ignored for other agents.
branch_name?stringOptional branch name for the session, only pass this if trying to work on an existing branch
pull_request_number?numberOptional existing pull request number to associate with this session
attach_pull_request?booleanWhether Inspect may automatically associate this session with an existing pull request that matches pull_request_number or branch_name. Set to false to check out branch_name without attaching its existing pull request. Pull requests created by this session are still attached. Defaults to true.
trueagent_context?stringOptional additional context for the agent that will not appear in user messages. Useful for providing detailed system context or metadata that should inform the agent but not clutter the visible conversation.
agent_id?stringOptional ID of an agent to use for this session. When provided, the session will be configured with the agent's system prompt, model, capability settings, and any repository restrictions. If the agent is limited to a set of repositories, the chosen repository must be within that set. Private agents cannot be started from the public API. Use GET /api/public/v1/agents to list available agents and their IDs.
is_readonly?booleanIf true, creates a read-only session where the agent cannot create PRs, push code, or make persistent changes. Useful for Q&A, research, or exploratory tasks.
falsevisibility?Sessions.SessionVisibilityControls whether the session appears in discoverable listings and analytics exports. Private sessions remain accessible by direct URL/session ID, but are excluded from list endpoints, public tables, leaderboards, and exports.
"public""private"settings?Optional session settings
collaborators?array<>Optional list of collaborator email addresses to add to the session. Users matching these emails will be added as session participants.
pr_footer?stringOptional custom footer text to append to PR descriptions. This will appear between the agent-generated description and the standard Inspect footer.
commit_prefix?stringOptional prefix to prepend to commit messages and PR titles. Useful for linking sessions to external systems like incident trackers or issue management tools.
pr_labels?array<>Optional list of GitHub labels to apply to any PR created or adopted by this session. Child sessions inherit these labels automatically.
tags?array<>Optional list of tags for grouping and filtering sessions (for example, run IDs, workflow names, or tenant keys).
items <= 50callback_url?stringOptional HTTPS webhook URL that the session can call back to via the api_callback tool. The hostname must be allowed by Inspect. When provided, the agent inside the session can send structured events to this URL, proxied through the Inspect API.
uriapi_callback_data_schema?Optional JSON Schema describing the expected shape of the data argument of the api_callback tool. Must be an object whose type, when present, is object. The schema is injected verbatim into the api_callback tool's description so the model knows what payload to send back.
api_callback_event_types?array<>Optional non-empty list of allowed event_type values for the api_callback tool. When provided, Inspect exposes those values as the tool schema enum and rejects callbacks whose event_type is not in the list.
1 <= itemsopencode_history?array<>Optional conversation history in OpenCode format to import into the session. When provided, the history is bulk-inserted as structured messages visible in the Inspect UI timeline, and the hosted agent is dispatched with noReply (the caller should send a follow-up prompt via POST /:session_id/prompt to start the agent).
opencode_history_source?Sessions.OpencodeHistorySourceOptional source of opencode_history, used to label imported messages and continuation context. Defaults to claude-code for backward compatibility.
"claude-code""codex""opencode"on_behalf_of?stringOptional email address of an existing Inspect user to create the session on behalf of. When provided, the session will be owned by and attributed to this user (including git commits and PR authorship) instead of the API key owner. The user must have logged into Inspect at least once.
emailIdempotency-Key replay - returns the session originally created for this key.
application/json- response
data*curl -X POST 'https://your-org.inspect.com/api/public/v1/sessions' \ -H 'Content-Type: application/json' \ -d '{ "repository": "string"}'{ "data": { "id": "string", "title": "string", "description": "string", "status": "pending", "retryable": true, "visibility": "public", "model": { "id": "string", "name": "string", "provider": "string", "variant": "string" }, "user": { "id": "string", "name": "string", "email": "string", "image": "string" }, "openingPr": true, "pushing": true, "workingPhase": "string", "deployed": true, "deployUrl": "string", "deployLastSucceededAt": "2019-08-24T14:15:22Z", "deployCommitSha": "string", "latestCommitSha": "string", "deploy": { "active": true, "url": "string", "commitSha": "string", "latestCommitSha": "string", "lastSucceededAt": "2019-08-24T14:15:22Z", "lastAttemptStatus": "succeeded", "lastAttemptCommitSha": "string", "lastAttemptStartedAt": 0, "timedOut": true, "outdated": true }, "vncUrl": "string", "vncExpiresAt": "2019-08-24T14:15:22Z", "otaInstallUrl": "string", "otaQrCodeUrl": "string", "otaExpiresAt": "2019-08-24T14:15:22Z", "hasChanges": true, "diffFileId": "string", "localDiffFileId": "string", "diffSource": "local", "diffAdditions": 0, "diffDeletions": 0, "createdAt": "2019-08-24T14:15:22Z", "finishedAt": "2019-08-24T14:15:22Z", "lastReadAt": "2019-08-24T14:15:22Z", "deletedAt": "2019-08-24T14:15:22Z", "pullRequests": [ { "repository": "string", "githubRepository": "string", "url": "http://example.com", "pullRequestNumber": 0, "adoptedAt": "2019-08-24T14:15:22Z", "statusUpdatedAt": "2019-08-24T14:15:22Z", "title": "string", "reviewBuddyInspectSessionId": "string", "approvalStatus": { "stampBuddy": { "sourceSequence": 0, "generation": 0, "publicationSequence": 0, "headSha": "string", "baseRef": "string", "viewStatus": "ready", "status": "not_started", "current": true, "reason": "string", "rationale": { "version": 1, "sections": [ { "title": "string", "items": [ { "title": "string", "status": "passed", "summary": "string", "sessions": [ "string" ], "details": [ { "label": "string", "text": "string", "values": [ "string" ] } ] } ] } ] }, "riskTier": "no_risk", "autoApproval": "pending", "history": [ { "headSha": "string", "sessionId": "string", "status": "not_started", "autoApproval": "pending", "updatedAt": "2019-08-24T14:15:22Z" } ], "grantApprovalBinding": "string", "updatedAt": "2019-08-24T14:15:22Z" }, "smartReviewer": { "sourceSequence": 0, "generation": 0, "publicationSequence": 0, "headSha": "string", "baseRef": "string", "status": "not_started", "current": true, "reason": "string", "recommendation": { "login": "string", "status": "available", "reasoning": "string", "selectionReason": "string" }, "requestReviewBinding": "string", "updatedAt": "2019-08-24T14:15:22Z" } }, "status": "draft", "mergedAt": "2019-08-24T14:15:22Z", "author": { "login": "string", "displayName": "string", "avatarUrl": "string", "profileUrl": "string" } } ], "repositories": [ { "id": "string", "isPrimary": true, "stateUpdatedAt": "2019-08-24T14:15:22Z", "branchName": "string", "baseBranch": "string", "latestCommitSha": "string", "diff": { "fileId": "string", "localFileId": "string", "source": "local", "additions": 0, "deletions": 0 } } ], "branchName": "string", "baseBranch": "string", "stackBaseBranch": "string", "helpfulness": 0, "helpfulnessReason": "string", "totalInputTokens": 0, "totalOutputTokens": 0, "totalReasoningTokens": 0, "totalCacheReadTokens": 0, "totalCacheWriteTokens": 0, "totalTokens": 0, "totalCost": 0, "lastUserMessageAt": "2019-08-24T14:15:22Z", "parentSessionId": "string", "projectId": "string", "childSessions": [ { "id": "string", "title": "string", "metadata": { "name": "string" }, "status": "pending", "createdAt": "2019-08-24T14:15:22Z" } ], "tags": [ "string" ], "metadata": { "runtime": "laminar", "laminarStartupPending": true, "laminarRuntime": { "sessionId": "string", "backend": "cell", "displayReadyAt": "string" }, "name": "string", "tags": [ "string" ], "prLabels": [ "string" ], "mobileDeployOtaCommitSha": "string", "hiddenFromDashboard": true, "projectCoordinator": true, "privateConnectorVisibility": { "connectorIds": [ "string" ], "connectorNames": [ "string" ], "forcedAt": "string" }, "lastDeployEventTs": 0, "lastDeployStatus": "succeeded", "lastDeployCommitSha": "string", "secondaryDeployUrls": {}, "customAgentPromptVersion": 0, "serviceTier": "string", "modelClass": "fast", "benchmarkFork": { "repoId": "string", "baseCommit": "string", "baseBranch": "string", "repo": "string" }, "reviewRequested": true, "reviewRequestDestinations": [ { "label": "string", "url": "string" } ], "autoMergeEnabled": true, "automationFanoutSummary": { "primaryChannelId": "string", "summaryMessageTs": "string", "entries": [ { "channelId": "string", "channelName": "string", "title": "string", "permalink": "string", "postedAt": "string", "targetRepo": "string", "priority": "high", "proposalId": "string", "proposalStatus": "closed", "childSessionId": "string" } ] }, "adminApiRequests": [ { "id": "string", "expiresAt": "string" } ], "githubInspectMentionCount": 0, "githubInspectMentionsPaused": true, "structuredOutput": { "status": "error", "output": null, "error": "string" }, "automationTrigger": { "type": "manual", "details": "string", "automationRunId": "string", "startingInternalState": {} } }, "automation": { "id": "string", "name": "string" }, "automationTriggerSource": "scheduled", "contextualActions": { "sourceAssistantMessageId": "string", "suggestions": [ { "actionKey": "send_prompt", "label": "string", "prompt": "string", "repository": "string", "pullRequestNumber": 0 } ] }, "settings": { "ciFailuresEnabled": true, "autoReviewEnabled": true, "autoAddressPrReviewsPolicy": { "enabled": true, "reviewerCategories": { "human": true, "bot": true }, "identityRules": [ { "selector": "string", "ruleType": "allow" } ], "reviewBuddy": { "enabled": true, "enabledFindingTypes": [ "critical" ] } } }, "isOwner": true, "isReadonly": true, "participants": [ { "id": "string", "sessionId": "string", "userId": "string", "joinedAt": "2019-08-24T14:15:22Z", "lastActiveAt": "2019-08-24T14:15:22Z", "leftAt": "2019-08-24T14:15:22Z", "user": { "id": "string", "name": "string", "email": "string", "image": "string" } } ], "agent": { "id": "string", "name": "string", "model": "string", "avatarUrl": "string" }, "workspace": { "id": "string", "name": "string", "description": "string", "organization": "string", "remote": "github", "githubHost": "github", "baseBranch": "string" }, "workspaceRef": "string", "repository": { "id": "string", "name": "string", "description": "string", "organization": "string", "remote": "github", "githubHost": "github", "baseBranch": "string" }, "pullRequest": { "pullRequestNumber": 0, "adoptedAt": "2019-08-24T14:15:22Z", "title": "string", "status": "draft", "mergedAt": "2019-08-24T14:15:22Z", "author": { "login": "string", "displayName": "string", "avatarUrl": "string", "profileUrl": "string" } }, "pullRequestNumber": 0, "pullRequestStatus": "draft" }}