StakPak Sessions API
The Sessions API from StakPak — 4 operation(s) for sessions.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/stakpak:stakpak-sessions-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Stakpak Sessions API
description: API for the Stakpak platform
license:
name: ''
version: 1.0.0
servers:
- url: https://apiv2.stakpak.dev
description: Production server
- url: http://localhost:4000
description: Local server
tags:
- name: Sessions
paths:
/v1/sessions:
get:
tags:
- Sessions
summary: List Sessions
description: Returns a paginated list of sessions for the authenticated user.
operationId: list_sessions_handler
parameters:
- name: limit
in: query
description: 'Number of sessions to return (default: 20, max: 100)'
required: false
schema:
type:
- integer
- 'null'
format: int32
minimum: 0
- name: offset
in: query
description: 'Offset for pagination (default: 0)'
required: false
schema:
type:
- integer
- 'null'
format: int32
minimum: 0
- name: search
in: query
description: Search in session titles
required: false
schema:
type:
- string
- 'null'
- name: status
in: query
description: 'Filter by status: ACTIVE, DELETED (default: ACTIVE)'
required: false
schema:
type:
- string
- 'null'
- name: visibility
in: query
description: 'Filter by visibility: PRIVATE, PUBLIC'
required: false
schema:
type:
- string
- 'null'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ListSessionsResponse'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- Api Key: []
post:
tags:
- Sessions
summary: Create Session
description: Creates a new session with an initial checkpoint.
operationId: create_session_handler
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSessionRequest'
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/CreateSessionResponse'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- Api Key: []
/v1/sessions/checkpoints/{checkpoint_id}:
get:
tags:
- Sessions
summary: Get Checkpoint
description: Returns a specific checkpoint by ID.
operationId: get_checkpoint_handler
parameters:
- name: checkpoint_id
in: path
description: Checkpoint ID
required: true
schema:
type: string
format: uuid
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/GetCheckpointResponse'
'404':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- Api Key: []
/v1/sessions/{session_id}:
get:
tags:
- Sessions
summary: Get Session
description: Returns a single session with its latest checkpoint.
operationId: get_session_handler
parameters:
- name: session_id
in: path
description: Session ID
required: true
schema:
type: string
format: uuid
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/GetSessionResponse'
'404':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- Api Key: []
delete:
tags:
- Sessions
summary: Delete Session
description: Soft deletes a session by setting its status to DELETED.
operationId: delete_session_handler
parameters:
- name: session_id
in: path
description: Session ID
required: true
schema:
type: string
format: uuid
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/DeleteSessionResponse'
'404':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- Api Key: []
patch:
tags:
- Sessions
summary: Update Session
description: Updates session metadata (title, visibility). Does not modify checkpoints.
operationId: update_session_handler
parameters:
- name: session_id
in: path
description: Session ID
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateSessionRequest'
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateSessionResponse'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- Api Key: []
/v1/sessions/{session_id}/checkpoints:
get:
tags:
- Sessions
summary: List Checkpoints
description: Returns all checkpoints for a session.
operationId: list_checkpoints_handler
parameters:
- name: session_id
in: path
description: Session ID
required: true
schema:
type: string
format: uuid
- name: limit
in: query
description: 'Number of checkpoints to return (default: 50, max: 100)'
required: false
schema:
type:
- integer
- 'null'
format: int32
minimum: 0
- name: offset
in: query
description: 'Offset for pagination (default: 0)'
required: false
schema:
type:
- integer
- 'null'
format: int32
minimum: 0
- name: include_state
in: query
description: 'Include full state in response (default: false)'
required: false
schema:
type:
- boolean
- 'null'
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ListCheckpointsResponse'
'404':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- Api Key: []
post:
tags:
- Sessions
summary: Create Checkpoint
description: Adds a checkpoint to an existing session.
operationId: create_checkpoint_handler
parameters:
- name: session_id
in: path
description: Session ID
required: true
schema:
type: string
format: uuid
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCheckpointRequest'
required: true
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/CreateCheckpointResponse'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'404':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
security:
- Api Key: []
components:
schemas:
FunctionCall:
type: object
required:
- name
- arguments
properties:
arguments:
type: string
name:
type: string
ChatMessage:
type: object
required:
- role
properties:
completed_at:
type:
- integer
- 'null'
format: int64
description: Unix timestamp (ms) when assistant finished generating
content:
oneOf:
- type: 'null'
- $ref: '#/components/schemas/MessageContent'
cost:
type:
- number
- 'null'
format: double
description: Cost in dollars for this message
created_at:
type:
- integer
- 'null'
format: int64
description: Unix timestamp (ms) when message was created/sent
finish_reason:
type:
- string
- 'null'
description: 'Why the model stopped: "stop", "tool_calls", "length", "error"'
id:
type:
- string
- 'null'
description: Unique message identifier
metadata:
description: Plugin extensibility - unstructured metadata
model:
oneOf:
- type: 'null'
- $ref: '#/components/schemas/ModelInfo'
description: Model that generated this message (for assistant messages)
name:
type:
- string
- 'null'
role:
$ref: '#/components/schemas/Role'
tool_call_id:
type:
- string
- 'null'
tool_calls:
type:
- array
- 'null'
items:
$ref: '#/components/schemas/ToolCall'
usage:
oneOf:
- type: 'null'
- $ref: '#/components/schemas/LLMTokenUsage'
CheckpointSummary:
type: object
description: Summary for listing checkpoints
required:
- id
- session_id
- message_count
- created_at
- updated_at
properties:
created_at:
type: string
format: date-time
id:
type: string
format: uuid
message_count:
type: integer
format: int32
minimum: 0
parent_id:
type:
- string
- 'null'
format: uuid
session_id:
type: string
format: uuid
state:
oneOf:
- type: 'null'
- $ref: '#/components/schemas/CheckpointState'
updated_at:
type: string
format: date-time
ErrorBody:
type: object
required:
- key
- message
properties:
key:
type: string
message:
type: string
ContentPart:
type: object
required:
- type
properties:
image_url:
oneOf:
- type: 'null'
- $ref: '#/components/schemas/ImageUrl'
text:
type:
- string
- 'null'
type:
type: string
CreateSessionResponse:
type: object
description: Response for creating a session
required:
- session_id
- checkpoint
properties:
checkpoint:
$ref: '#/components/schemas/Checkpoint'
session_id:
type: string
format: uuid
SessionStatus:
type: string
enum:
- ACTIVE
- DELETED
UpdateSessionRequest:
type: object
description: Request body for updating a session
properties:
title:
type:
- string
- 'null'
description: New title for the session
visibility:
oneOf:
- type: 'null'
- $ref: '#/components/schemas/SessionVisibility'
description: New visibility for the session
LLMTokenUsage:
type: object
required:
- prompt_tokens
- completion_tokens
- total_tokens
properties:
completion_tokens:
type: integer
format: int32
minimum: 0
prompt_tokens:
type: integer
format: int32
minimum: 0
prompt_tokens_details:
oneOf:
- type: 'null'
- $ref: '#/components/schemas/PromptTokensDetails'
total_tokens:
type: integer
format: int32
minimum: 0
ErrorResponse:
type: object
required:
- error
properties:
error:
$ref: '#/components/schemas/ErrorBody'
CreateCheckpointRequest:
type: object
description: Request body for creating a checkpoint in an existing session
required:
- state
properties:
parent_id:
type:
- string
- 'null'
format: uuid
description: 'Parent checkpoint for branching (optional).
Defaults to latest checkpoint if not provided.'
state:
$ref: '#/components/schemas/CheckpointState'
description: Checkpoint state with messages
Role:
type: string
enum:
- system
- developer
- user
- assistant
- tool
Checkpoint:
type: object
description: Full checkpoint with state
required:
- id
- session_id
- state
- created_at
- updated_at
properties:
created_at:
type: string
format: date-time
id:
type: string
format: uuid
parent_id:
type:
- string
- 'null'
format: uuid
session_id:
type: string
format: uuid
state:
$ref: '#/components/schemas/CheckpointState'
updated_at:
type: string
format: date-time
Session:
type: object
description: Full session with active checkpoint
required:
- id
- title
- visibility
- status
- created_at
- updated_at
properties:
active_checkpoint:
oneOf:
- type: 'null'
- $ref: '#/components/schemas/Checkpoint'
created_at:
type: string
format: date-time
cwd:
type:
- string
- 'null'
deleted_at:
type:
- string
- 'null'
format: date-time
id:
type: string
format: uuid
status:
$ref: '#/components/schemas/SessionStatus'
title:
type: string
updated_at:
type: string
format: date-time
visibility:
$ref: '#/components/schemas/SessionVisibility'
MessageContent:
oneOf:
- type: string
- type: array
items:
$ref: '#/components/schemas/ContentPart'
SessionSummary:
type: object
description: Summary for listing sessions (without full checkpoint state)
required:
- id
- title
- visibility
- status
- created_at
- updated_at
- message_count
- active_checkpoint_id
properties:
active_checkpoint_id:
type: string
format: uuid
created_at:
type: string
format: date-time
cwd:
type:
- string
- 'null'
id:
type: string
format: uuid
last_message_at:
type:
- string
- 'null'
format: date-time
message_count:
type: integer
format: int32
minimum: 0
status:
$ref: '#/components/schemas/SessionStatus'
title:
type: string
updated_at:
type: string
format: date-time
visibility:
$ref: '#/components/schemas/SessionVisibility'
UpdateSessionResponse:
type: object
description: Response for updating a session
required:
- session
properties:
session:
$ref: '#/components/schemas/Session'
GetCheckpointResponse:
type: object
description: Response for getting a single checkpoint
required:
- checkpoint
properties:
checkpoint:
$ref: '#/components/schemas/Checkpoint'
GetSessionResponse:
type: object
description: Response for getting a single session
required:
- session
properties:
session:
$ref: '#/components/schemas/Session'
DeleteSessionResponse:
type: object
description: Response for deleting a session
required:
- success
- deleted_at
properties:
deleted_at:
type: string
format: date-time
success:
type: boolean
ToolCall:
type: object
required:
- id
- type
- function
properties:
function:
$ref: '#/components/schemas/FunctionCall'
id:
type: string
type:
type: string
CreateSessionRequest:
type: object
description: Request body for creating a new session
required:
- title
- state
properties:
cwd:
type:
- string
- 'null'
description: Working directory context
state:
$ref: '#/components/schemas/CheckpointState'
description: Initial checkpoint state with messages
title:
type: string
description: Title for the session (required)
visibility:
oneOf:
- type: 'null'
- $ref: '#/components/schemas/SessionVisibility'
description: 'Session visibility (default: PRIVATE)'
PromptTokensDetails:
type: object
properties:
cache_read_input_tokens:
type: integer
format: int32
minimum: 0
cache_write_input_tokens:
type: integer
format: int32
minimum: 0
input_tokens:
type: integer
format: int32
minimum: 0
output_tokens:
type: integer
format: int32
minimum: 0
CheckpointState:
type: object
description: Checkpoint state - only messages, no workflow-specific fields
properties:
messages:
type: array
items:
$ref: '#/components/schemas/ChatMessage'
ListSessionsResponse:
type: object
description: Response for listing sessions
required:
- sessions
properties:
sessions:
type: array
items:
$ref: '#/components/schemas/SessionSummary'
ListCheckpointsResponse:
type: object
description: Response for listing checkpoints
required:
- checkpoints
properties:
checkpoints:
type: array
items:
$ref: '#/components/schemas/CheckpointSummary'
ImageUrl:
type: object
required:
- url
properties:
detail:
type:
- string
- 'null'
url:
type: string
ModelInfo:
type: object
description: Model information for tracking which model generated a message
required:
- provider
- id
properties:
id:
type: string
description: Model identifier (e.g., "claude-sonnet-4-20250514", "gpt-4")
provider:
type: string
description: Provider name (e.g., "anthropic", "openai")
SessionVisibility:
type: string
enum:
- PRIVATE
- PUBLIC
CreateCheckpointResponse:
type: object
description: Response for creating a checkpoint
required:
- checkpoint
properties:
checkpoint:
$ref: '#/components/schemas/Checkpoint'
securitySchemes:
Api_Key:
type: http
scheme: bearer
bearerFormat: JWT
Token:
type: http
scheme: bearer
bearerFormat: JWT
cookie:
type: apiKey
in: cookie
name: .idToken