Skip to main content
POST
Create a new session
With the default Member and Admin roles, each API key can call this endpoint. On Enterprise, a custom or edited role must include the Use Devin Sessions permission (UseDevinSessions). The session is created on behalf of the user the API key belongs to.

Limits and validation

  • prompt must be 30,000 characters or fewer; longer prompts return 400.
  • tags accepts at most 50 tags, each a non-empty string of at most 256 characters. Enterprises that enforce required tags reject reserved tag names with 400.
  • structured_output_schema must be a valid JSON Schema (Draft 7) with "type": "object" at the root, contain no external $ref, and be at most 64 KB; otherwise the request returns 400.
  • is_new_session in the response is only set when the request uses idempotency_key (or the deprecated idempotent); otherwise it is null.

Authorizations

Authorization
string
header
required

Personal API Key (apk_user_*) or Service API Key (apk_*)

Body

application/json
prompt
string
required
idempotent
boolean
default:false
knowledge_ids
string[] | null

List of knowledge IDs to use. If None, use all knowledge. If empty list, use no knowledge.

max_acu_limit
integer | null

Maximum ACU limit, must be positive

Required range: x > 0
playbook_id
string | null
secret_ids
string[] | null

List of secret IDs to use. If None, use all secrets. If empty list, use no secrets.

session_secrets
SessionSecretInput · object[] | null

List of session-specific secrets to use. These secrets are only available in this session and are not stored in organization secrets.

snapshot_id
string | null
structured_output_schema
Structured Output Schema · object | null

JSON Schema (Draft 7) for validating structured output. Max 64KB. Must be self-contained (no external $ref).

tags
string[] | null

List of tags to add to the session.

Maximum array length: 50
title
string | null

Custom title for the session. If None, a title will be generated automatically.

unlisted
boolean
default:false

Response

Successful Response

Response body returned when a session is successfully created.

session_id
string
required
url
string
required
is_new_session
boolean | null