cURL

curl --request GET \
  --url https://davinci-app.com/api/v2/projects/{projectId}/sessions/{sessionId} \
  --header 'Authorization: Bearer <token>'

import os
from davinci_sdk import DavinciClient

with DavinciClient(api_key=os.environ["DAVINCI_API_KEY"]) as client:
    refreshed = client.sessions.get(project_id, session_id)
    print(refreshed.data_plane.expires_at, refreshed.agent.status)

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

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

const refreshed = await client.sessions.get(projectId, sessionId);
console.log(refreshed.dataPlane.expiresAt, refreshed.agent?.status);

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://davinci-app.com/api/v2/projects/{projectId}/sessions/{sessionId}', 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": {}
  }
}

Sessions

Read a session, refresh its grant, and check the agent

Returns the session with a new grant and revokes the previous one, so a leaked grant stops working at the next poll rather than at its expiry.

This is also the keepalive, for both clocks that matter: the grant’s expiry and the machine’s idle timer. Call it well before dataPlane.expiresAt — the SDKs do this for you.

agent.status is how you follow a run started with sendAgentMessage. It is reported here rather than on a route of its own precisely so that one poll keeps the session alive and tells you where the run is. completed, failed, and paused are terminal; paused is what a stopAgent produces. unknown means the machine could not be reached for this field alone — the grant in the same response is still good, so retry rather than recreating the session.

GET

api

projects

{projectId}

sessions

{sessionId}

cURL

curl --request GET \
  --url https://davinci-app.com/api/v2/projects/{projectId}/sessions/{sessionId} \
  --header 'Authorization: Bearer <token>'

import os
from davinci_sdk import DavinciClient

with DavinciClient(api_key=os.environ["DAVINCI_API_KEY"]) as client:
    refreshed = client.sessions.get(project_id, session_id)
    print(refreshed.data_plane.expires_at, refreshed.agent.status)

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

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

const refreshed = await client.sessions.get(projectId, sessionId);
console.log(refreshed.dataPlane.expiresAt, refreshed.agent?.status);

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://davinci-app.com/api/v2/projects/{projectId}/sessions/{sessionId}', 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": {}
  }
}

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

sessionId

string<uuid>

required

Session id from createSession.

Response

The session, with a freshly minted grant.

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

Read a session, refresh its grant, and check the agent

Authorizations

Path Parameters

Response