cURL

curl --request POST \
  --url https://davinci-app.com/api/v2/projects/{projectId}/sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "branch": "<string>",
  "scopes": [],
  "ttlSeconds": 900
}
'

import os
from davinci_sdk import DavinciClient

with DavinciClient(api_key=os.environ["DAVINCI_API_KEY"]) as client:
    session = client.sessions.create(project_id)
    print(session.session_id, session.data_plane.url)

import { DavinciClient } from '@celedon/davinci-sdk';

const client = new DavinciClient({
  apiKey: process.env.DAVINCI_API_KEY!,
});

const session = await client.sessions.create(projectId);
console.log(session.sessionId, session.dataPlane.url);

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({branch: '<string>', scopes: [], ttlSeconds: 900})
};

fetch('https://davinci-app.com/api/v2/projects/{projectId}/sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "projectId": "<string>",
  "branchName": "<string>",
  "ownerId": "<string>",
  "dataPlane": {
    "url": "<string>",
    "token": "<string>",
    "expiresAt": "2023-11-07T05:31:56Z",
    "connectionId": "<string>",
    "ownerId": "<string>",
    "userId": "<string>",
    "projectKey": "<string>",
    "operations": [
      "<string>"
    ]
  },
  "agent": {
    "status": "no_session",
    "taskId": "<string>",
    "lastMessageId": "<string>"
  }
}

{
  "success": false,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  }
}

{
  "success": false,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  }
}

{
  "success": false,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  }
}

{
  "success": false,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  }
}

{
  "success": false,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  }
}

{
  "success": false,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  }
}

{
  "success": false,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  }
}

Sessions

Open a session and mint a data-plane grant

Loads the project, holds it open, and returns the credential for reaching it directly.

A project unloads shortly after nothing is connected to it, so a session is what keeps it resident between your requests. Poll the session (getSession) to both refresh the grant and signal that you are still working.

The grant can never exceed the key that minted it. Omit scopes to inherit the key’s own scopes; supply them to narrow the grant further, which is worth doing when one job needs less than the key can do.

POST

api

projects

{projectId}

sessions

cURL

curl --request POST \
  --url https://davinci-app.com/api/v2/projects/{projectId}/sessions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "branch": "<string>",
  "scopes": [],
  "ttlSeconds": 900
}
'

import os
from davinci_sdk import DavinciClient

with DavinciClient(api_key=os.environ["DAVINCI_API_KEY"]) as client:
    session = client.sessions.create(project_id)
    print(session.session_id, session.data_plane.url)

import { DavinciClient } from '@celedon/davinci-sdk';

const client = new DavinciClient({
  apiKey: process.env.DAVINCI_API_KEY!,
});

const session = await client.sessions.create(projectId);
console.log(session.sessionId, session.dataPlane.url);

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({branch: '<string>', scopes: [], ttlSeconds: 900})
};

fetch('https://davinci-app.com/api/v2/projects/{projectId}/sessions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "sessionId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "projectId": "<string>",
  "branchName": "<string>",
  "ownerId": "<string>",
  "dataPlane": {
    "url": "<string>",
    "token": "<string>",
    "expiresAt": "2023-11-07T05:31:56Z",
    "connectionId": "<string>",
    "ownerId": "<string>",
    "userId": "<string>",
    "projectKey": "<string>",
    "operations": [
      "<string>"
    ]
  },
  "agent": {
    "status": "no_session",
    "taskId": "<string>",
    "lastMessageId": "<string>"
  }
}

{
  "success": false,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  }
}

{
  "success": false,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  }
}

{
  "success": false,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  }
}

{
  "success": false,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  }
}

{
  "success": false,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  }
}

{
  "success": false,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  }
}

{
  "success": false,
  "error": {
    "code": "<string>",
    "message": "<string>",
    "details": {}
  }
}

Authorizations

Authorization

string

header

default:dav_ak_live_your_token

required

Personal access token. The scopes granted at issuance determine both which operations the key may call and the ceiling on the resource permissions it can exercise. Each scope family is a ladder: projects:manage implies projects:write and projects:read; cards:manage implies cards:write and cards:read; and teams:manage implies teams:write and teams:read. These are named API capability bundles, not blanket domain roles: manage exposes only the permissions enumerated for that scope and never bypasses the acting user's current role-based access.

Path Parameters

projectId

string

required

Project id. May be compound in the form {projectId}--{branchName}.

Minimum string length: 1

Body

application/json

branch

string | null

Branch to open. Defaults to the branch in a compound project id, or main.

scopes

enum<string>[]

Narrow the grant below the key's own scopes. Omit to inherit them. Asking for a scope the key does not hold is refused rather than silently reduced.

Available options:

projects:read,

projects:write,

projects:manage,

sessions:manage,

agent:message,

webhooks:receive,

usage:read

ttlSeconds

integer

default:900

Grant lifetime. Capped at one hour regardless of what is requested.

Required range: 1 <= x <= 3600

Response

The session, with the grant needed to reach the data plane.

sessionId

string<uuid>

required

projectId

string

required

Bare project id, without the branch suffix.

branchName

string

required

ownerId

string

required

Account or organization that owns the project. Files live under the owner's storage namespace, not the caller's, which is why a shared or org-owned project needs this rather than your own user id.

dataPlane

object

required

Everything needed to address the data plane: where to send, what to send with, and the path parameters that are not obvious from the project id alone.

Hide child attributes

dataPlane.url

string<uri>

required

Base URL for data-plane operations. Names no specific machine, so it stays valid if the project moves.

dataPlane.token

string

required

The grant, dav_gr_…. Returned only here and only once — it is not stored in recoverable form, so a lost grant is replaced by refreshing the session rather than looked up.

dataPlane.expiresAt

string<date-time>

required

dataPlane.connectionId

string

required

Pass as the connectionId path parameter on upload.

dataPlane.ownerId

string

required

Pass as the ownerId path parameter.

dataPlane.userId

string

required

Pass as the userId path parameter on upload.

dataPlane.projectKey

string

required

Pass as the projectId path parameter. Compound form {projectId}--{branchName}, since the data plane addresses a branch.

dataPlane.operations

string[]

required

Data-plane operations this grant authorizes.

agent

object

What the session's agent is doing. Present on a session read, absent on create because nothing has been asked of the agent yet.

Hide child attributes

agent.status

enum<string>

required

no_session — the machine has no record of this session; it lapsed or the project restarted. Create a new one.
project_not_running — the session is known but its project has unloaded.
idle — the session is live and no run has been started.
starting — a run is being set up.
running — a run is in progress.
paused — a run was stopped and can be continued with a new prompt.
completed — the run finished.
failed — the run ended in an error. The transcript says why.
unknown — the machine could not be reached for this field. Retry; anything else in the same response is still valid.

paused, completed, and failed are terminal for a run.

Available options:

no_session,

project_not_running,

idle,

starting,

running,

paused,

completed,

failed,

unknown

agent.taskId

string | null

Identifies the run. Also names the stored conversation.

agent.lastMessageId

string | null

The messageId of the most recent prompt the agent took.

Getting Started

Davinci Browser

Davinci Editor

Integrations

Modeling Guide

Developer API

Examples

Release Notes

Open a session and mint a data-plane grant

Authorizations

Path Parameters

Body

Response