Default | codeset - Documentation

Health Check

get

Health check endpoint

Responses

200

Successful Response

application/json

Response model for health check endpoint.

statusstringRequired

Health status of the service

servicestringRequired

Name of the service

versionstringRequired

Version of the service

timestampstringRequired

Timestamp when the health check was performed (ISO format)

get

/health

Python

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)

200

Successful Response

{
  "status": "text",
  "service": "text",
  "version": "text",
  "timestamp": "text"
}

Github Oauth

post

Authenticate user with GitHub OAuth

Body

Request for GitHub OAuth authentication.

codestringRequired

Authorization code from GitHub OAuth.

stateany ofOptional

State parameter for CSRF protection.

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

Response for GitHub OAuth authentication.

user_idstringRequired

Unique identifier for the user.

access_tokenstringRequired

JWT access token for the user.

refresh_tokenstringRequired

JWT refresh token for the user.

token_typestringOptional

Token type.

Default: Bearer

expires_inintegerRequired

Access token expiration time in seconds.

is_new_userbooleanRequired

Whether this is a new user or existing user.

422

Validation Error

application/json

post

/auth/github

POST /api/v1/auth/github HTTP/1.1
Content-Type: application/json
Accept: */*
Content-Length: 30

{
  "code": "text",
  "state": "text"
}

{
  "user_id": "text",
  "access_token": "text",
  "refresh_token": "text",
  "token_type": "Bearer",
  "expires_in": 1,
  "is_new_user": true
}

Refresh Token

post

Refresh an access token using a refresh token

Body

Request to refresh an access token.

refresh_tokenstringRequired

The refresh token.

Responses

200

Successful Response

application/json

Response for token refresh.

access_tokenstringRequired

New JWT access token.

token_typestringOptional

Token type.

Default: Bearer

expires_inintegerRequired

Access token expiration time in seconds.

422

Validation Error

application/json

post

/auth/refresh

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

get

Get current user information

Authorizations

AuthorizationstringRequired

Bearer token for API authentication

Responses

200

Successful Response

application/json

Represents a user in the system.

user_idstringRequired

Unique identifier for the user.

namestringRequired

Display name of the user.

emailstringRequired

Email address of the user.

github_idany ofOptional

GitHub user ID for OAuth authentication.

stringOptional

or

nullOptional

created_atstring · date-timeRequired

Timestamp when the user was created (UTC).

last_login_atany ofOptional

Timestamp of the user's last login (UTC).

string · date-timeOptional

or

nullOptional

is_activebooleanOptional

Whether the user account is active.

Default: true

get

/users/me

GET /api/v1/users/me HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

Successful Response

{
  "user_id": "text",
  "name": "text",
  "email": "text",
  "github_id": "text",
  "api_keys": [
    {
      "key_id": "text",
      "key": "text",
      "name": "text",
      "created_at": "2026-03-05T05:34:44.052Z",
      "expires_at": "2026-03-05T05:34:44.052Z",
      "is_active": true,
      "last_used_at": "2026-03-05T05:34:44.052Z"
    }
  ],
  "created_at": "2026-03-05T05:34:44.052Z",
  "last_login_at": "2026-03-05T05:34:44.052Z",
  "is_active": true
}

Create Api Key

post

Create a new API key for the current user

Authorizations

AuthorizationstringRequired

Bearer token for API authentication

Body

Request to create a new API key for a user.

nameany ofOptional

Optional name for the API key.

stringOptional

or

nullOptional

Responses

200

Successful Response

application/json

Response for creating an API key.

422

Validation Error

application/json

post

/users/me/api-keys

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-03-05T05:34:44.052Z",
    "expires_at": "2026-03-05T05:34:44.052Z",
    "is_active": true,
    "last_used_at": "2026-03-05T05:34:44.052Z"
  }
}

Revoke Api Key

delete

Revoke an API key for the current user

Authorizations

AuthorizationstringRequired

Bearer token for API authentication

Body

Request to revoke an API key.

key_idstringRequired

The ID of the API key to revoke.

Responses

200

Successful Response

application/json

Response for revoking an API key.

messagestringRequired

Success message.

revoked_key_idstringRequired

The ID of the revoked API key.

422

Validation Error

application/json

delete

/users/me/api-keys

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 Datasets

get

List available datasets

Responses

200

Successful Response

application/json

Information about a dataset.

namestringRequired

Unique name of the dataset.

descriptionany ofOptional

A brief description of the dataset.

stringOptional

or

nullOptional

sample_countintegerRequired

Number of samples in the dataset.

created_atany ofOptional

Timestamp when the dataset was first created (UTC).

string · date-timeOptional

or

nullOptional

get

/datasets

Python

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)

200

Successful Response

[
  {
    "name": "text",
    "description": "text",
    "sample_count": 1,
    "created_at": "2026-03-05T05:34:44.052Z"
  }
]

List Samples

get

List available samples with optional pagination, optionally filtered by dataset

Query parameters

datasetany ofOptional

Filter samples by dataset name

stringOptional

or

nullOptional

searchany ofOptional

Search for samples by instance_id

stringOptional

or

nullOptional

pageany ofOptional

Page number (1-based). If not provided, returns all samples

integer · min: 1Optional

or

nullOptional

page_sizeany ofOptional

Number of samples per page (max 100). If not provided, returns all samples

integer · min: 1 · max: 100Optional

or

nullOptional

Responses

200

Successful Response

application/json

Response for listing samples with pagination.

total_countintegerRequired

Total number of samples available.

pageintegerRequired

Current page number (1-based).

page_sizeintegerRequired

Number of samples per page.

has_morebooleanRequired

Indicates if more pages of results are available.

422

Validation Error

application/json

get

/samples

Python

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-03-05T05:34:44.052Z",
      "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 Sample

get

Download the gz file for a specific sample

Authorizations

AuthorizationstringRequired

Bearer token for API authentication

Path parameters

datasetstringRequired

sample_idstringRequired

Query parameters

versionany ofOptional

integerOptional

or

nullOptional

Responses

200

Successful Response

application/json

anyOptional

422

Validation Error

application/json

get

/samples/{dataset}/{sample_id}/download

Python

from codeset import Codeset

client = Codeset()
response = client.samples.download(
    sample_id="sample_id",
    dataset="dataset",
)
print(response)

No content

List Sessions

get

List environment sessions

Authorizations

AuthorizationstringRequired

Bearer token for API authentication

Responses

200

Successful Response

application/json

Response for listing sessions.

total_countintegerRequired

Total number of sessions returned.

has_morebooleanRequired

Indicates if more pages of results are available.

get

/sessions

Python

from codeset import Codeset

client = Codeset()
sessions = client.sessions.list()
print(sessions.has_more)

200

Successful Response

{
  "sessions": [
    {
      "session_id": "text",
      "user_id": "text",
      "dataset": "text",
      "sample_id": "text",
      "status": "creating",
      "requested_at": "2026-03-05T05:34:44.052Z",
      "created_at": "2026-03-05T05:34:44.052Z",
      "expires_at": "2026-03-05T05:34:44.052Z",
      "duration_seconds": 1,
      "container_info": {
        "container_name": "text",
        "service_url": "https://example.com",
        "sample_id": "text",
        "status": "text",
        "created_at": "2026-03-05T05:34:44.052Z",
        "expires_at": "2026-03-05T05:34:44.052Z",
        "location": "text"
      },
      "error": {
        "code": "text",
        "message": "text"
      }
    }
  ],
  "total_count": 1,
  "has_more": true
}

Create Session

post

Create a new session

Authorizations

AuthorizationstringRequired

Bearer token for API authentication

Body

Request to create a new session.

datasetstringRequired

Dataset name for the sample.

sample_idstringRequired

Identifier of the sample to use for this session.

ttl_minutesintegerOptional

Time to live for the session in minutes (default: 30).

Default: 30

Responses

201

Successful Response

application/json

422

Validation Error

application/json

post

/sessions

Python

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-03-05T05:34:44.052Z"
}

Get Session

get

Get session details

Authorizations

AuthorizationstringRequired

Bearer token for API authentication

Path parameters

session_idstringRequired

Responses

200

Successful Response

application/json

Represents a session for multi-turn interactions.

session_idstringRequired

Unique identifier for the session.

user_idstringRequired

User ID who owns this session.

datasetstringRequired

Dataset name for the sample.

sample_idstringRequired

Identifier of the sample being used for the session.

statusstring · enumRequired

Current status of the session.

Possible values:

requested_atstring · date-timeRequired

Timestamp when the session was requested (UTC).

created_atany ofOptional

Timestamp when the container became ready and billing started (UTC).

string · date-timeOptional

or

nullOptional

expires_atstring · date-timeRequired

Timestamp when the session will expire (UTC).

duration_secondsany ofOptional

Duration of the session in seconds.

numberOptional

or

nullOptional

container_infoany ofOptional

Container information for this session.

or

nullOptional

errorany ofOptional

Error details if the session failed.

or

nullOptional

422

Validation Error

application/json

get

/sessions/{session_id}

Python

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-03-05T05:34:44.052Z",
  "created_at": "2026-03-05T05:34:44.052Z",
  "expires_at": "2026-03-05T05:34:44.052Z",
  "duration_seconds": 1,
  "container_info": {
    "container_name": "text",
    "service_url": "https://example.com",
    "sample_id": "text",
    "status": "text",
    "created_at": "2026-03-05T05:34:44.052Z",
    "expires_at": "2026-03-05T05:34:44.052Z",
    "location": "text"
  },
  "error": {
    "code": "text",
    "message": "text"
  }
}

Close Session

delete

Close/delete an environment session

Authorizations

AuthorizationstringRequired

Bearer token for API authentication

Path parameters

session_idstringRequired

Responses

200

Successful Response

application/json

Response model for session deletion.

messagestringRequired

Success message confirming session deletion

duration_secondsnumberRequired

Duration of the session in seconds.

422

Validation Error

application/json

delete

/sessions/{session_id}

Python

from codeset import Codeset

client = Codeset()
response = client.sessions.close(
    "session_id",
)
print(response.duration_seconds)

{
  "message": "text",
  "duration_seconds": 1
}

Execute Command

post

Start command execution in an environment (async)

Authorizations

AuthorizationstringRequired

Bearer token for API authentication

Path parameters

session_idstringRequired

Body

Request to execute a bash command in a session.

commandstringRequired

The bash command to execute.

command_timeoutintegerOptional

Timeout for command execution in seconds (default: 300).

Default: 300

Responses

202

Successful Response

application/json

422

Validation Error

application/json

post

/sessions/{session_id}/exec

Python

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

get

Get interaction details by ID

Authorizations

AuthorizationstringRequired

Bearer token for API authentication

Path parameters

interaction_idstringRequired

session_idstringRequired

Responses

200

Successful Response

application/json

or

422

Validation Error

application/json

get

/sessions/{session_id}/interactions/{interaction_id}

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-03-05T05:34:44.052Z",
  "exit_code": 1,
  "stdout": "text",
  "stderr": "text",
  "execution_time_seconds": 1,
  "success": true,
  "message": "text",
  "command": "text",
  "command_timeout": 300
}

String Replace

post

Replace a string in a file within the session environment

Authorizations

AuthorizationstringRequired

Bearer token for API authentication

Path parameters

session_idstringRequired

Body

Request to perform string replacement in a file.

file_pathstringRequired

Path to the file where replacement should be performed.

str_to_replacestringRequired

String to be replaced.

str_to_insertstringRequired

String to insert as replacement.

Responses

200

Successful Response

application/json

Response for string replacement operation.

successbooleanRequired

Whether the string replacement was successful.

messagestringRequired

Details about the string replacement operation.

422

Validation Error

application/json

post

/sessions/{session_id}/str_replace

Python

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"
}

Start Verification

post

Start verification (oracle) in a session - async

Authorizations

AuthorizationstringRequired

Bearer token for API authentication

Path parameters

session_idstringRequired

Responses

202

Successful Response

application/json

422

Validation Error

application/json

post

/sessions/{session_id}/verify

Python

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-03-05T05:34:44.052Z"
}

Get Verification Job

get

Get a verification job, including the result if it's completed

Authorizations

AuthorizationstringRequired

Bearer token for API authentication

Path parameters

job_idstringRequired

session_idstringRequired

Responses

200

Successful Response

application/json

Represents a single verification job, the core resource of the API.

job_idstringRequired

Unique identifier for the job.

sample_idstringRequired

Identifier of the sample being used for verification.

session_idstringRequired

Session identifier for this job.

statusstring · enumRequired

Current status of the job.

Possible values:

created_atstring · date-timeRequired

Timestamp when the job was created (UTC).

started_atany ofOptional

Timestamp when the job processing started (UTC).

string · date-timeOptional

or

nullOptional

completed_atany ofOptional

Timestamp when the job completed (UTC).

string · date-timeOptional

or

nullOptional

resultany ofOptional

The result of the verification. Available when status is 'completed'.

anyOptional

or

nullOptional

errorany ofOptional

Error details if the job failed with an 'error' status.

or

nullOptional

container_infoany ofOptional

Container information for this job.

or

nullOptional

422

Validation Error

application/json

get

/sessions/{session_id}/verify/{job_id}

Python

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-03-05T05:34:44.052Z",
  "started_at": "2026-03-05T05:34:44.052Z",
  "completed_at": "2026-03-05T05:34:44.052Z",
  "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-03-05T05:34:44.052Z",
    "expires_at": "2026-03-05T05:34:44.052Z",
    "location": "text"
  }
}

Get User Balance

get

Get user's money balance

Authorizations

AuthorizationstringRequired

Bearer token for API authentication

Responses

200

Successful Response

application/json

User's money balance and billing information

user_idstringRequired

User ID

balanceintegerOptional

Current balance in cents

Default: 0

total_depositedintegerOptional

Total money ever deposited in cents

Default: 0

total_spentintegerOptional

Total money ever spent in cents

Default: 0

stripe_customer_idany ofOptional

Stripe customer ID

stringOptional

or

nullOptional

last_updatedstring · date-timeRequired

Last time balance was updated

get

/billing/balance

GET /api/v1/billing/balance HTTP/1.1
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

200

Successful Response

{
  "user_id": "text",
  "balance": 0,
  "total_deposited": 0,
  "total_spent": 0,
  "stripe_customer_id": "text",
  "last_updated": "2026-03-05T05:34:44.052Z"
}

Get Pricing Info

get

Get current pricing information

Responses

200

Successful Response

application/json

Other propertiesanyOptional

get

/billing/pricing

GET /api/v1/billing/pricing HTTP/1.1
Accept: */*

200

Successful Response

{
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

Deposit Money

post

Create a payment intent for money deposit

Authorizations

AuthorizationstringRequired

Bearer token for API authentication

Body

Request to deposit money

amount_centsinteger · min: 500Required

Amount to deposit in cents

currencystringOptional

Currency for payment

Default: usd

Responses

200

Successful Response

application/json

Response for money deposit

checkout_urlstringRequired

Stripe checkout URL for payment

amount_centsintegerRequired

Amount being deposited in cents

currencystringRequired

Currency

422

Validation Error

application/json

post

/billing/deposit

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"
}

Stripe Webhook

post

Handle Stripe webhook events

Responses

200

Successful Response

application/json

Other propertiesanyOptional

post

/billing/webhook

POST /api/v1/billing/webhook HTTP/1.1
Accept: */*

200

Successful Response

{
  "ANY_ADDITIONAL_PROPERTY": "anything"
}

Get Usage History

get

Get complete usage history for the current user

Authorizations

AuthorizationstringRequired

Bearer token for API authentication

Query parameters

pageinteger · min: 1Optional

Page number (1-based)

Default: 1

limitinteger · min: 1 · max: 100Optional

Items per page (max 100)

Default: 25

Responses

200

Successful Response

application/json

Complete usage history for a user

current_balance_centsintegerRequired

Current balance in cents

total_deposits_centsintegerRequired

Total amount deposited

total_usage_centsintegerRequired

Total amount used

422

Validation Error

application/json

get

/billing/usage

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-03-05T05:34:44.052Z",
      "session_id": "text",
      "duration_minutes": 1
    }
  ],
  "summary": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  },
  "pagination": {
    "ANY_ADDITIONAL_PROPERTY": "anything"
  }
}

hashtagHealth Check

hashtagGithub Oauth

hashtagRefresh Token

hashtagGet Current User

hashtagCreate Api Key

hashtagRevoke Api Key

hashtagList Datasets

hashtagList Samples

hashtagDownload Sample

hashtagList Sessions

hashtagCreate Session

hashtagGet Session

hashtagClose Session

hashtagExecute Command

hashtagGet Interaction

hashtagString Replace

hashtagStart Verification

hashtagGet Verification Job

hashtagGet User Balance

hashtagGet Pricing Info

hashtagDeposit Money

hashtagStripe Webhook

hashtagGet Usage History

Health Check

Github Oauth

Refresh Token

Get Current User

Create Api Key

Revoke Api Key

List Datasets

List Samples

Download Sample

List Sessions

Create Session

Get Session

Close Session

Execute Command

Get Interaction

String Replace

Start Verification

Get Verification Job

Get User Balance

Get Pricing Info

Deposit Money

Stripe Webhook

Get Usage History