Sessions
Browser sessions an agent recorded: a title, how it ended, the git commit and pull request, and attachments such as a trace, screenshots and a video.
A session is not a run. It does not appear in run lists or in analytics, and it has no spec files or tests. Share one with POST /share and sessionId.
Records a browser session and signs an upload URL for each attachment declared in the request. Upload each file with a PUT to its uploadUrl, sending the headers in uploadHeaders; when sizeBytes was sent, the body must be exactly that long. The session is complete when created: there is nothing to finish. Besides a bearer token, this route accepts a record key in the x-currents-key header.
An organization API key, sent as Authorization: Bearer <key>. A key carries one scope for the whole API: a read key reaches the GET endpoints, a write key reaches all of them. A crnts_pat_ personal access token is accepted as a Bearer while its owner remains an eligible administrator in its active organization. Each operation requires the corresponding scope stored on that token.
What the session set out to show
For a failed session
The session ID and upload URLs, in the order of the request
Invalid request parameters
Authentication failed
The credential authenticated but is not permitted to use this endpoint. Five refusals share the status: a read API key on an endpoint that writes, an OAuth token that was not granted the scope the endpoint needs (insufficient_scope), an OAuth token that was granted it but whose holder no longer has a role permitting it (insufficient_role), an OAuth token on an endpoint that accepts an API key and nothing else (api_key_required), and an API key on an endpoint that answers for a user (user_credential_required). Discriminate on code rather than on the message, which is free-form. The first refusal predates the codes and sets none. Only insufficient_scope carries the challenge header, because it is the only one a client can act on by re-authorizing.
Resource not found
Recording is suspended or the subscription has expired
Too many requests for the organization (rate_limited)
POST /v1/sessions HTTP/1.1
Host: api.currents.dev
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 456
{
"projectId": "text",
"title": "text",
"status": "passed",
"error": "text",
"durationMs": 1,
"tags": [
"text"
],
"commit": {
"sha": "text",
"branch": "text",
"message": "text",
"authorName": "text",
"authorEmail": "text",
"remoteOrigin": "text"
},
"pr": {
"link": "text",
"id": "text"
},
"ci": {
"provider": "text",
"buildNumber": "text",
"params": {}
},
"attachments": [
{
"name": "text",
"type": "trace",
"contentType": "image/png",
"sizeBytes": 1,
"caption": "text",
"meta": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
]
}{
"status": "OK",
"data": {
"sessionId": "text",
"uploadExpiresInSeconds": 600,
"attachments": [
{
"attachmentId": "text",
"name": "text",
"type": "text",
"uploadUrl": "text",
"uploadHeaders": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
]
}
}The session and its attachments, oldest first, each with a read URL signed for an hour.
An organization API key, sent as Authorization: Bearer <key>. A key carries one scope for the whole API: a read key reaches the GET endpoints, a write key reaches all of them. A crnts_pat_ personal access token is accepted as a Bearer while its owner remains an eligible administrator in its active organization. Each operation requires the corresponding scope stored on that token.
The session ID
The session
Authentication failed
The credential authenticated but is not permitted to use this endpoint. Five refusals share the status: a read API key on an endpoint that writes, an OAuth token that was not granted the scope the endpoint needs (insufficient_scope), an OAuth token that was granted it but whose holder no longer has a role permitting it (insufficient_role), an OAuth token on an endpoint that accepts an API key and nothing else (api_key_required), and an API key on an endpoint that answers for a user (user_credential_required). Discriminate on code rather than on the message, which is free-form. The first refusal predates the codes and sets none. Only insufficient_scope carries the challenge header, because it is the only one a client can act on by re-authorizing.
Resource not found
GET /v1/sessions/{sessionId} HTTP/1.1
Host: api.currents.dev
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"status": "OK",
"data": {
"sessionId": "text",
"projectId": "text",
"title": "text",
"status": "passed",
"error": "text",
"tags": [
"text"
],
"durationMs": 1,
"git": {
"sha": "text",
"branch": "text",
"message": "text",
"authorName": "text",
"authorEmail": "text",
"remoteOrigin": "text"
},
"pr": {
"id": "text",
"link": "text",
"title": "text",
"source": "text",
"destination": "text"
},
"attachmentCount": 1,
"createdAt": "2026-01-01T00:00:00.000Z",
"cursor": "text",
"attachments": [
{
"attachmentId": "text",
"name": "text",
"type": "trace",
"contentType": "text",
"sizeBytes": 1,
"caption": "text",
"meta": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"createdAt": "2026-01-01T00:00:00.000Z",
"readUrl": "text"
}
]
}
}The session stops being readable at once. Its attachments, share links and share assets are removed in the background.
An organization API key, sent as Authorization: Bearer <key>. A key carries one scope for the whole API: a read key reaches the GET endpoints, a write key reaches all of them. A crnts_pat_ personal access token is accepted as a Bearer while its owner remains an eligible administrator in its active organization. Each operation requires the corresponding scope stored on that token.
The session ID
Deleted
Authentication failed
The credential authenticated but is not permitted to use this endpoint. Five refusals share the status: a read API key on an endpoint that writes, an OAuth token that was not granted the scope the endpoint needs (insufficient_scope), an OAuth token that was granted it but whose holder no longer has a role permitting it (insufficient_role), an OAuth token on an endpoint that accepts an API key and nothing else (api_key_required), and an API key on an endpoint that answers for a user (user_credential_required). Discriminate on code rather than on the message, which is free-form. The first refusal predates the codes and sets none. Only insufficient_scope carries the challenge header, because it is the only one a client can act on by re-authorizing.
Resource not found
DELETE /v1/sessions/{sessionId} HTTP/1.1
Host: api.currents.dev
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"status": "OK"
}An organization API key, sent as Authorization: Bearer <key>. A key carries one scope for the whole API: a read key reaches the GET endpoints, a write key reaches all of them. A crnts_pat_ personal access token is accepted as a Bearer while its owner remains an eligible administrator in its active organization. Each operation requires the corresponding scope stored on that token.
The session ID
The attachments, oldest first
Authentication failed
The credential authenticated but is not permitted to use this endpoint. Five refusals share the status: a read API key on an endpoint that writes, an OAuth token that was not granted the scope the endpoint needs (insufficient_scope), an OAuth token that was granted it but whose holder no longer has a role permitting it (insufficient_role), an OAuth token on an endpoint that accepts an API key and nothing else (api_key_required), and an API key on an endpoint that answers for a user (user_credential_required). Discriminate on code rather than on the message, which is free-form. The first refusal predates the codes and sets none. Only insufficient_scope carries the challenge header, because it is the only one a client can act on by re-authorizing.
Resource not found
GET /v1/sessions/{sessionId}/attachments HTTP/1.1
Host: api.currents.dev
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"status": "OK",
"data": {
"attachments": [
{
"attachmentId": "text",
"name": "text",
"type": "trace",
"contentType": "text",
"sizeBytes": 1,
"caption": "text",
"meta": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"createdAt": "2026-01-01T00:00:00.000Z",
"readUrl": "text"
}
]
}
}Signs an upload URL for each attachment. A session takes at most 200 attachments. The body takes no target fields such as instanceId or testId: a session has none. Besides a bearer token, this route accepts a record key in the x-currents-key header.
An organization API key, sent as Authorization: Bearer <key>. A key carries one scope for the whole API: a read key reaches the GET endpoints, a write key reaches all of them. A crnts_pat_ personal access token is accepted as a Bearer while its owner remains an eligible administrator in its active organization. Each operation requires the corresponding scope stored on that token.
The session ID
Upload URLs, in the order of the request
Invalid request parameters
Authentication failed
The credential authenticated but is not permitted to use this endpoint. Five refusals share the status: a read API key on an endpoint that writes, an OAuth token that was not granted the scope the endpoint needs (insufficient_scope), an OAuth token that was granted it but whose holder no longer has a role permitting it (insufficient_role), an OAuth token on an endpoint that accepts an API key and nothing else (api_key_required), and an API key on an endpoint that answers for a user (user_credential_required). Discriminate on code rather than on the message, which is free-form. The first refusal predates the codes and sets none. Only insufficient_scope carries the challenge header, because it is the only one a client can act on by re-authorizing.
Resource not found
Too many requests for the organization (rate_limited)
POST /v1/sessions/{sessionId}/attachments HTTP/1.1
Host: api.currents.dev
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 147
{
"attachments": [
{
"name": "text",
"type": "trace",
"contentType": "image/png",
"sizeBytes": 1,
"caption": "text",
"meta": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
]
}{
"status": "OK",
"data": {
"sessionId": "text",
"uploadExpiresInSeconds": 600,
"attachments": [
{
"attachmentId": "text",
"name": "text",
"type": "text",
"uploadUrl": "text",
"uploadHeaders": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}
]
}
}Newest first. Filters match as they do on the run list; search looks at the title, branch, commit message and pull request.
An organization API key, sent as Authorization: Bearer <key>. A key carries one scope for the whole API: a read key reaches the GET endpoints, a write key reaches all of them. A crnts_pat_ personal access token is accepted as a Bearer while its owner remains an eligible administrator in its active organization. Each operation requires the corresponding scope stored on that token.
The project ID
proj_abc123Maximum number of items to return (default: 10, max: 50)
10Cursor for pagination. Returns items after this cursor value.
Cursor for pagination. Returns items before this cursor value.
Filter by tags (can be specified multiple times using bracket notation, e.g., tags[]=value1&tags[]=value2)
["tag1","tag2"]Logical operator for tag filtering. AND requires all tags to be present (default), OR requires any tag to be present.
ANDExample: ANDPossible values: Filter runs by normalized pull request id (stored as meta.pr.id). Printable ASCII only, max 128 characters.
42Pattern: ^[!-~]+$Case-insensitive substring search over a session's title, branch, commit message, and pull request id and title. Printable ASCII only; leading and trailing whitespace is trimmed, and the trimmed value must be 1–200 characters.
^[ -~]+$Filter runs created on or after this ISO 8601 date-time. A date without a time (2024-01-01) means midnight UTC of that day.
2024-01-01T00:00:00ZFilter runs created before this ISO 8601 date-time. A date without a time (2024-12-31) means midnight UTC of that day, so the range ends before that day.
2024-12-31T23:59:59ZA page of sessions, without their attachments
Invalid request parameters
Authentication failed
The credential authenticated but is not permitted to use this endpoint. Five refusals share the status: a read API key on an endpoint that writes, an OAuth token that was not granted the scope the endpoint needs (insufficient_scope), an OAuth token that was granted it but whose holder no longer has a role permitting it (insufficient_role), an OAuth token on an endpoint that accepts an API key and nothing else (api_key_required), and an API key on an endpoint that answers for a user (user_credential_required). Discriminate on code rather than on the message, which is free-form. The first refusal predates the codes and sets none. Only insufficient_scope carries the challenge header, because it is the only one a client can act on by re-authorizing.
Resource not found
GET /v1/projects/{projectId}/sessions HTTP/1.1
Host: api.currents.dev
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"status": "OK",
"has_more": true,
"data": [
{
"sessionId": "text",
"projectId": "text",
"title": "text",
"status": "passed",
"error": "text",
"tags": [
"text"
],
"durationMs": 1,
"git": {
"sha": "text",
"branch": "text",
"message": "text",
"authorName": "text",
"authorEmail": "text",
"remoteOrigin": "text"
},
"pr": {
"id": "text",
"link": "text",
"title": "text",
"source": "text",
"destination": "text"
},
"attachmentCount": 1,
"createdAt": "2026-01-01T00:00:00.000Z",
"cursor": "text"
}
]
}Last updated
Was this helpful?