Default | codeset - Documentation

Health Check

get

Health check endpoint

Responses

200

Successful Response

application/json

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

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

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

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-02-14T19:26:52.854Z",
      "expires_at": "2026-02-14T19:26:52.854Z",
      "is_active": true,
      "last_used_at": "2026-02-14T19:26:52.854Z"
    }
  ],
  "created_at": "2026-02-14T19:26:52.854Z",
  "last_login_at": "2026-02-14T19:26:52.854Z",
  "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

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-02-14T19:26:52.854Z",
    "expires_at": "2026-02-14T19:26:52.854Z",
    "is_active": true,
    "last_used_at": "2026-02-14T19:26:52.854Z"
  }
}

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

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

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-02-14T19:26:52.854Z"
  }
]

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

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-02-14T19:26:52.854Z",
      "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

Responseany

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

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-02-14T19:26:52.854Z",
      "created_at": "2026-02-14T19:26:52.854Z",
      "expires_at": "2026-02-14T19:26:52.854Z",
      "duration_seconds": 1,
      "container_info": {
        "container_name": "text",
        "service_url": "https://example.com",
        "sample_id": "text",
        "status": "text",
        "created_at": "2026-02-14T19:26:52.854Z",
        "expires_at": "2026-02-14T19:26:52.854Z",
        "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-02-14T19:26:52.854Z"
}

Get Session

get

Get session details

Authorizations

AuthorizationstringRequired

Bearer token for API authentication

Path parameters

session_idstringRequired

Responses

200

Successful Response

application/json

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-02-14T19:26:52.854Z",
  "created_at": "2026-02-14T19:26:52.854Z",
  "expires_at": "2026-02-14T19:26:52.854Z",
  "duration_seconds": 1,
  "container_info": {
    "container_name": "text",
    "service_url": "https://example.com",
    "sample_id": "text",
    "status": "text",
    "created_at": "2026-02-14T19:26:52.854Z",
    "expires_at": "2026-02-14T19:26:52.854Z",
    "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

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

Responseany of

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-02-14T19:26:52.854Z",
  "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

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-02-14T19:26:52.854Z"
}

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

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-02-14T19:26:52.854Z",
  "started_at": "2026-02-14T19:26:52.854Z",
  "completed_at": "2026-02-14T19:26:52.854Z",
  "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-02-14T19:26:52.854Z",
    "expires_at": "2026-02-14T19:26:52.854Z",
    "location": "text"
  }
}

Get User Balance

get

Get user's money balance

Authorizations

AuthorizationstringRequired

Bearer token for API authentication

Responses

200

Successful Response

application/json

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-02-14T19:26:52.854Z"
}

Get Pricing Info

get

Get current pricing information

Responses

200

Successful Response

application/json

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

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

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

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-02-14T19:26:52.854Z",
      "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