Codeset API
Health check endpoint
Successful Response
Response model for health check endpoint.
Health status of the service
Name of the service
Version of the service
Timestamp when the health check was performed (ISO format)
import os
from codeset import Codeset
client = Codeset(
api_key=os.environ.get("CODESET_API_KEY"), # This is the default and can be omitted
)
response = client.health.check()
print(response.service)Successful Response
{
"status": "text",
"service": "text",
"version": "text",
"timestamp": "text"
}Authenticate user with GitHub OAuth
Request for GitHub OAuth authentication.
Authorization code from GitHub OAuth.
State parameter for CSRF protection.
Callback URL used in the authorize step; must match app settings.
Successful Response
Response for GitHub OAuth authentication.
Unique identifier for the user.
JWT access token for the user.
JWT refresh token for the user.
Token type.
BearerAccess token expiration time in seconds.
Whether this is a new user or existing user.
Validation Error
POST /api/v1/auth/github HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 52
{
"code": "text",
"state": "text",
"redirect_uri": "text"
}{
"user_id": "text",
"access_token": "text",
"refresh_token": "text",
"token_type": "Bearer",
"expires_in": 1,
"is_new_user": true
}Bearer token for API authentication
Successful Response
GET /api/v1/repos HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
Successful Response
{
"repos": [
{
"full_name": "text",
"private": true,
"html_url": "text"
}
]
}Refresh an access token using a refresh token
Request to refresh an access token.
The refresh token.
Successful Response
Response for token refresh.
New JWT access token.
Token type.
BearerAccess token expiration time in seconds.
Validation Error
POST /api/v1/auth/refresh HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 24
{
"refresh_token": "text"
}{
"access_token": "text",
"token_type": "Bearer",
"expires_in": 1
}Get current user information
Bearer token for API authentication
Successful Response
Represents a user in the system.
Unique identifier for the user.
Display name of the user.
Email address of the user.
GitHub user ID for OAuth authentication.
GitHub username (login) for matching app installations.
Timestamp when the user was created (UTC).
Timestamp of the user's last login (UTC).
Whether the user account is active.
trueWhen the user last accepted the terms of service (UTC). None if not accepted.
GET /api/v1/users/me HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
Successful Response
{
"user_id": "text",
"name": "text",
"email": "text",
"github_id": "text",
"github_login": "text",
"api_keys": [
{
"key_id": "text",
"key": "text",
"name": "text",
"created_at": "2026-01-01T00:00:00.000Z",
"expires_at": "2026-01-01T00:00:00.000Z",
"is_active": true,
"last_used_at": "2026-01-01T00:00:00.000Z"
}
],
"created_at": "2026-01-01T00:00:00.000Z",
"last_login_at": "2026-01-01T00:00:00.000Z",
"is_active": true,
"terms_accepted_at": "2026-01-01T00:00:00.000Z"
}Record that the current user has accepted the terms of service.
Bearer token for API authentication
Successful Response
Represents a user in the system.
Unique identifier for the user.
Display name of the user.
Email address of the user.
GitHub user ID for OAuth authentication.
GitHub username (login) for matching app installations.
Timestamp when the user was created (UTC).
Timestamp of the user's last login (UTC).
Whether the user account is active.
trueWhen the user last accepted the terms of service (UTC). None if not accepted.
POST /api/v1/users/me/accept-terms HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
Successful Response
{
"user_id": "text",
"name": "text",
"email": "text",
"github_id": "text",
"github_login": "text",
"api_keys": [
{
"key_id": "text",
"key": "text",
"name": "text",
"created_at": "2026-01-01T00:00:00.000Z",
"expires_at": "2026-01-01T00:00:00.000Z",
"is_active": true,
"last_used_at": "2026-01-01T00:00:00.000Z"
}
],
"created_at": "2026-01-01T00:00:00.000Z",
"last_login_at": "2026-01-01T00:00:00.000Z",
"is_active": true,
"terms_accepted_at": "2026-01-01T00:00:00.000Z"
}Create a new API key for the current user
Bearer token for API authentication
Request to create a new API key for a user.
Optional name for the API key.
Successful Response
Response for creating an API key.
Validation Error
POST /api/v1/users/me/api-keys HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 15
{
"name": "text"
}{
"api_key": {
"key_id": "text",
"key": "text",
"name": "text",
"created_at": "2026-01-01T00:00:00.000Z",
"expires_at": "2026-01-01T00:00:00.000Z",
"is_active": true,
"last_used_at": "2026-01-01T00:00:00.000Z"
}
}Revoke an API key for the current user
Bearer token for API authentication
Request to revoke an API key.
The ID of the API key to revoke.
Successful Response
Response for revoking an API key.
Success message.
The ID of the revoked API key.
Validation Error
DELETE /api/v1/users/me/api-keys HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 17
{
"key_id": "text"
}{
"message": "text",
"revoked_key_id": "text"
}List available datasets
Successful Response
Information about a dataset.
Unique name of the dataset.
A brief description of the dataset.
Number of samples in the dataset.
Timestamp when the dataset was first created (UTC).
import os
from codeset import Codeset
client = Codeset(
api_key=os.environ.get("CODESET_API_KEY"), # This is the default and can be omitted
)
datasets = client.datasets.list()
print(datasets)Successful Response
[
{
"name": "text",
"description": "text",
"sample_count": 1,
"created_at": "2026-01-01T00:00:00.000Z"
}
]List available samples with optional pagination, optionally filtered by dataset
Filter samples by dataset name
Search for samples by instance_id
Page number (1-based). If not provided, returns all samples
Number of samples per page (max 100). If not provided, returns all samples
Successful Response
Response for listing samples with pagination.
Total number of samples available.
Current page number (1-based).
Number of samples per page.
Indicates if more pages of results are available.
Validation Error
import os
from codeset import Codeset
client = Codeset(
api_key=os.environ.get("CODESET_API_KEY"), # This is the default and can be omitted
)
samples = client.samples.list()
print(samples.has_more){
"samples": [
{
"sample_id": "text",
"description": "text",
"language": "text",
"verifier": "test_suite",
"dataset": "text",
"version": 1,
"version_description": "text",
"latest": true,
"created_at": "2026-01-01T00:00:00.000Z",
"instance_id": "text",
"repo": "text",
"base_commit": "text",
"patch": "text",
"non_code_patch": "text",
"test_patch": "text",
"problem_statement": "text",
"hints_text": "text",
"environment_setup_commit": "text",
"fail_to_pass": [
"text"
],
"pass_to_pass": [
"text"
],
"fail_to_fail": [
"text"
]
}
],
"total_count": 1,
"page": 1,
"page_size": 1,
"has_more": true
}Download the gz file for a specific sample
Bearer token for API authentication
Successful Response
Validation Error
from codeset import Codeset
client = Codeset()
response = client.samples.download(
sample_id="sample_id",
dataset="dataset",
)
print(response)No content
List environment sessions
Bearer token for API authentication
Successful Response
Response for listing sessions.
Total number of sessions returned.
Indicates if more pages of results are available.
from codeset import Codeset
client = Codeset()
sessions = client.sessions.list()
print(sessions.has_more)Successful Response
{
"sessions": [
{
"session_id": "text",
"user_id": "text",
"dataset": "text",
"sample_id": "text",
"status": "creating",
"requested_at": "2026-01-01T00:00:00.000Z",
"created_at": "2026-01-01T00:00:00.000Z",
"expires_at": "2026-01-01T00:00:00.000Z",
"duration_seconds": 1,
"container_info": {
"container_name": "text",
"service_url": "https://example.com",
"sample_id": "text",
"status": "text",
"created_at": "2026-01-01T00:00:00.000Z",
"expires_at": "2026-01-01T00:00:00.000Z",
"location": "text"
},
"error": {
"code": "text",
"message": "text"
}
}
],
"total_count": 1,
"has_more": true
}Create a new session
Bearer token for API authentication
Request to create a new session.
Dataset name for the sample.
Identifier of the sample to use for this session.
Time to live for the session in minutes (default: 30).
30Successful Response
Response for creating a session.
Unique identifier for the created session.
Initial status of the session.
Timestamp when the session will expire (UTC).
Validation Error
from codeset import Codeset
client = Codeset()
session = client.sessions.create(
dataset="dataset",
sample_id="sample_id",
)
print(session.session_id){
"session_id": "text",
"status": "creating",
"expires_at": "2026-01-01T00:00:00.000Z"
}Get session details
Bearer token for API authentication
Successful Response
Represents a session for multi-turn interactions.
Unique identifier for the session.
User ID who owns this session.
Dataset name for the sample.
Identifier of the sample being used for the session.
Current status of the session.
Timestamp when the session was requested (UTC).
Timestamp when the container became ready and billing started (UTC).
Timestamp when the session will expire (UTC).
Duration of the session in seconds.
Validation Error
from codeset import Codeset
client = Codeset()
session = client.sessions.retrieve(
"session_id",
)
print(session.sample_id){
"session_id": "text",
"user_id": "text",
"dataset": "text",
"sample_id": "text",
"status": "creating",
"requested_at": "2026-01-01T00:00:00.000Z",
"created_at": "2026-01-01T00:00:00.000Z",
"expires_at": "2026-01-01T00:00:00.000Z",
"duration_seconds": 1,
"container_info": {
"container_name": "text",
"service_url": "https://example.com",
"sample_id": "text",
"status": "text",
"created_at": "2026-01-01T00:00:00.000Z",
"expires_at": "2026-01-01T00:00:00.000Z",
"location": "text"
},
"error": {
"code": "text",
"message": "text"
}
}Close/delete an environment session
Bearer token for API authentication
Successful Response
Response model for session deletion.
Success message confirming session deletion
Duration of the session in seconds.
Validation Error
from codeset import Codeset
client = Codeset()
response = client.sessions.close(
"session_id",
)
print(response.duration_seconds){
"message": "text",
"duration_seconds": 1
}Start command execution in an environment (async)
Bearer token for API authentication
Request to execute a bash command in a session.
The bash command to execute.
Timeout for command execution in seconds (default: 300).
300Successful Response
Response for starting command execution (async).
Unique identifier for the interaction.
Status of the interaction: 'pending', 'processing', 'completed', or 'failed'.
Validation Error
from codeset import Codeset
client = Codeset()
response = client.sessions.execute_command(
session_id="session_id",
command="command",
)
print(response.interaction_id){
"interaction_id": "text",
"status": "text"
}Get interaction details by ID
Bearer token for API authentication
Successful Response
Validation Error
GET /api/v1/sessions/{session_id}/interactions/{interaction_id} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"interaction_id": "text",
"session_id": "text",
"interaction_type": "exec_command",
"created_at": "2026-01-01T00:00:00.000Z",
"exit_code": 1,
"stdout": "text",
"stderr": "text",
"execution_time_seconds": 1,
"success": true,
"message": "text",
"command": "text",
"command_timeout": 300
}Replace a string in a file within the session environment
Bearer token for API authentication
Request to perform string replacement in a file.
Path to the file where replacement should be performed.
String to be replaced.
String to insert as replacement.
Successful Response
Response for string replacement operation.
Whether the string replacement was successful.
Details about the string replacement operation.
Validation Error
from codeset import Codeset
client = Codeset()
response = client.sessions.str_replace(
session_id="session_id",
file_path="file_path",
str_to_insert="str_to_insert",
str_to_replace="str_to_replace",
)
print(response.message){
"success": true,
"message": "text"
}Upload a file to the session environment
Bearer token for API authentication
Request to upload a file to the session environment.
Destination path for the file inside the container.
Base64-encoded file content.
Whether to make the file executable (chmod +x).
falseSuccessful Response
Response for file upload operation.
Whether the file upload was successful.
Details about the file upload operation.
Destination path where the file was written.
Size of the uploaded file in bytes.
Validation Error
POST /api/v1/sessions/{session_id}/upload HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 68
{
"file_path": "text",
"content_base64": "text",
"make_executable": false
}{
"success": true,
"message": "text",
"file_path": "text",
"size_bytes": 1
}Start verification (oracle) in a session - async
Bearer token for API authentication
Successful Response
Response for starting verification (async).
Unique identifier for the verification job.
Initial status of the verification job.
Timestamp when verification started (UTC).
Validation Error
from codeset import Codeset
client = Codeset()
response = client.sessions.verify.start(
"session_id",
)
print(response.job_id){
"job_id": "text",
"status": "pending",
"started_at": "2026-01-01T00:00:00.000Z"
}Get a verification job, including the result if it's completed
Bearer token for API authentication
Successful Response
Represents a single verification job, the core resource of the API.
Unique identifier for the job.
Identifier of the sample being used for verification.
Session identifier for this job.
Current status of the job.
Timestamp when the job was created (UTC).
Timestamp when the job processing started (UTC).
Timestamp when the job completed (UTC).
The result of the verification. Available when status is 'completed'.
Validation Error
from codeset import Codeset
client = Codeset()
response = client.sessions.verify.status(
job_id="job_id",
session_id="session_id",
)
print(response.job_id){
"job_id": "text",
"sample_id": "text",
"session_id": "text",
"status": "pending",
"created_at": "2026-01-01T00:00:00.000Z",
"started_at": "2026-01-01T00:00:00.000Z",
"completed_at": "2026-01-01T00:00:00.000Z",
"result": {
"tool": "test_suite",
"is_success": true,
"execution_duration_seconds": 1,
"total": 1,
"passed": 1,
"failed": 1,
"skipped": 1,
"passes": [],
"failures": [],
"skips": [],
"stdout": "PLACE_HOLDER",
"stderr": "PLACE_HOLDER"
},
"error": {
"code": "text",
"message": "text"
},
"container_info": {
"container_name": "text",
"service_url": "https://example.com",
"sample_id": "text",
"status": "text",
"created_at": "2026-01-01T00:00:00.000Z",
"expires_at": "2026-01-01T00:00:00.000Z",
"location": "text"
}
}Get user's money balance
Bearer token for API authentication
Successful Response
User's money balance and billing information
User ID
Current balance in cents
0Total money ever deposited in cents
0Total money ever spent in cents
0Stripe customer ID
Last time balance was updated
GET /api/v1/billing/balance HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
Successful Response
{
"user_id": "text",
"balance": 0,
"total_deposited": 0,
"total_spent": 0,
"stripe_customer_id": "text",
"last_updated": "2026-01-01T00:00:00.000Z"
}Create a payment intent for money deposit
Bearer token for API authentication
Request to deposit money
Amount to deposit in cents
Currency for payment
usdSuccessful Response
Response for money deposit
Stripe checkout URL for payment
Amount being deposited in cents
Currency
Validation Error
POST /api/v1/billing/deposit HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 35
{
"amount_cents": 1,
"currency": "usd"
}{
"checkout_url": "text",
"amount_cents": 1,
"currency": "text"
}Get complete usage history for the current user
Bearer token for API authentication
Page number (1-based)
1Items per page (max 100)
25Include only transactions on or after this date (UTC).
Include only transactions on or before this date (UTC).
Filter by transaction type(s): deposit, usage, charge, refund, agent_job_usage, agent_job_refund.
Max transactions to load (default: all). Ignored when start_date or end_date is set.
Successful Response
Complete usage history for a user
Current balance in cents
Total amount deposited
Total amount used
Validation Error
GET /api/v1/billing/usage HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"current_balance_cents": 1,
"total_deposits_cents": 1,
"total_usage_cents": 1,
"transactions": [
{
"id": "text",
"type": "deposit",
"amount_cents": 1,
"description": "text",
"created_at": "2026-01-01T00:00:00.000Z",
"session_id": "text",
"duration_minutes": 1,
"job_id": "text"
}
],
"summary": {
"ANY_ADDITIONAL_PROPERTY": "anything"
},
"pagination": {
"ANY_ADDITIONAL_PROPERTY": "anything"
}
}Bearer token for API authentication
20Successful Response
Validation Error
GET /api/v1/agent-jobs HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"ANY_ADDITIONAL_PROPERTY": "anything"
}Bearer token for API authentication
Repository identifier as owner/repo.
Optional ref or branch.
Agent type (e.g. cursor).
Successful Response
Validation Error
POST /api/v1/agent-jobs HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 46
{
"repo": "text",
"ref": "text",
"agent_id": "text"
}{
"ANY_ADDITIONAL_PROPERTY": "anything"
}Bearer token for API authentication
Successful Response
Validation Error
GET /api/v1/agent-jobs/{job_id} HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"ANY_ADDITIONAL_PROPERTY": "anything"
}Must match the job's completion_secret.
When outcome is error, stored on the job.
Successful Response
Validation Error
POST /api/v1/agent-jobs/{job_id}/completion HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 62
{
"secret": "text",
"outcome": "completed",
"error_message": "text"
}{
"ANY_ADDITIONAL_PROPERTY": "anything"
}Bearer token for API authentication
Successful Response
Validation Error
GET /api/v1/agent-jobs/{job_id}/result HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
No content
Last updated