# Codeset API ## Health Check > Health check endpoint ```json {"openapi":"3.1.0","info":{"title":"Codeset API","version":"1.0.0"},"servers":[{"url":"/api/v1"}],"paths":{"/health":{"get":{"summary":"Health Check","description":"Health check endpoint","operationId":"health_check_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HealthCheckResponse"}}}}}}}},"components":{"schemas":{"HealthCheckResponse":{"properties":{"status":{"type":"string","title":"Status","description":"Health status of the service"},"service":{"type":"string","title":"Service","description":"Name of the service"},"version":{"type":"string","title":"Version","description":"Version of the service"},"timestamp":{"type":"string","title":"Timestamp","description":"Timestamp when the health check was performed (ISO format)"}},"type":"object","required":["status","service","version","timestamp"],"title":"HealthCheckResponse","description":"Response model for health check endpoint."}}}} ``` ## Github Oauth > Authenticate user with GitHub OAuth ```json {"openapi":"3.1.0","info":{"title":"Codeset API","version":"1.0.0"},"servers":[{"url":"/api/v1"}],"paths":{"/auth/github":{"post":{"summary":"Github Oauth","description":"Authenticate user with GitHub OAuth","operationId":"github_oauth_auth_github_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GitHubOAuthRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GitHubOAuthResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"GitHubOAuthRequest":{"properties":{"code":{"type":"string","title":"Code","description":"Authorization code from GitHub OAuth."},"state":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"State","description":"State parameter for CSRF protection."},"redirect_uri":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Redirect Uri","description":"Callback URL used in the authorize step; must match app settings."}},"type":"object","required":["code"],"title":"GitHubOAuthRequest","description":"Request for GitHub OAuth authentication."},"GitHubOAuthResponse":{"properties":{"user_id":{"type":"string","title":"User Id","description":"Unique identifier for the user."},"access_token":{"type":"string","title":"Access Token","description":"JWT access token for the user."},"refresh_token":{"type":"string","title":"Refresh Token","description":"JWT refresh token for the user."},"token_type":{"type":"string","title":"Token Type","description":"Token type.","default":"Bearer"},"expires_in":{"type":"integer","title":"Expires In","description":"Access token expiration time in seconds."},"is_new_user":{"type":"boolean","title":"Is New User","description":"Whether this is a new user or existing user."}},"type":"object","required":["user_id","access_token","refresh_token","expires_in","is_new_user"],"title":"GitHubOAuthResponse","description":"Response for GitHub OAuth authentication."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}} ``` ## GET /repos > List Repos ```json {"openapi":"3.1.0","info":{"title":"Codeset API","version":"1.0.0"},"servers":[{"url":"/api/v1"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","description":"Bearer token for API authentication","scheme":"bearer"}},"schemas":{"GitHubReposResponse":{"properties":{"repos":{"items":{"$ref":"#/components/schemas/GitHubRepoItem"},"type":"array","title":"Repos","description":"List of repositories."}},"type":"object","required":["repos"],"title":"GitHubReposResponse"},"GitHubRepoItem":{"properties":{"full_name":{"type":"string","title":"Full Name","description":"Repository full name (owner/repo)."},"private":{"type":"boolean","title":"Private","description":"Whether the repository is private."},"html_url":{"type":"string","title":"Html Url","description":"Repository URL."}},"type":"object","required":["full_name","private","html_url"],"title":"GitHubRepoItem"}}},"paths":{"/repos":{"get":{"summary":"List Repos","operationId":"list_repos_repos_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GitHubReposResponse"}}}}}}}}} ``` ## Refresh Token > Refresh an access token using a refresh token ```json {"openapi":"3.1.0","info":{"title":"Codeset API","version":"1.0.0"},"servers":[{"url":"/api/v1"}],"paths":{"/auth/refresh":{"post":{"summary":"Refresh Token","description":"Refresh an access token using a refresh token","operationId":"refresh_token_auth_refresh_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenRefreshRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TokenRefreshResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"TokenRefreshRequest":{"properties":{"refresh_token":{"type":"string","title":"Refresh Token","description":"The refresh token."}},"type":"object","required":["refresh_token"],"title":"TokenRefreshRequest","description":"Request to refresh an access token."},"TokenRefreshResponse":{"properties":{"access_token":{"type":"string","title":"Access Token","description":"New JWT access token."},"token_type":{"type":"string","title":"Token Type","description":"Token type.","default":"Bearer"},"expires_in":{"type":"integer","title":"Expires In","description":"Access token expiration time in seconds."}},"type":"object","required":["access_token","expires_in"],"title":"TokenRefreshResponse","description":"Response for token refresh."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}} ``` ## Get Current User > Get current user information ```json {"openapi":"3.1.0","info":{"title":"Codeset API","version":"1.0.0"},"servers":[{"url":"/api/v1"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","description":"Bearer token for API authentication","scheme":"bearer"}},"schemas":{"User":{"properties":{"user_id":{"type":"string","title":"User Id","description":"Unique identifier for the user."},"name":{"type":"string","title":"Name","description":"Display name of the user."},"email":{"type":"string","title":"Email","description":"Email address of the user."},"github_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Github Id","description":"GitHub user ID for OAuth authentication."},"github_login":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Github Login","description":"GitHub username (login) for matching app installations."},"api_keys":{"items":{"$ref":"#/components/schemas/ApiKey"},"type":"array","title":"Api Keys","description":"List of API keys associated with this user."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Timestamp when the user was created (UTC)."},"last_login_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Login At","description":"Timestamp of the user's last login (UTC)."},"is_active":{"type":"boolean","title":"Is Active","description":"Whether the user account is active.","default":true},"terms_accepted_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Terms Accepted At","description":"When the user last accepted the terms of service (UTC). None if not accepted."}},"type":"object","required":["user_id","name","email","created_at"],"title":"User","description":"Represents a user in the system."},"ApiKey":{"properties":{"key_id":{"type":"string","title":"Key Id","description":"Unique identifier for the API key."},"key":{"type":"string","title":"Key","description":"The actual API key value."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Optional name for the API key."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Timestamp when the API key was created (UTC)."},"expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expires At","description":"Timestamp when the API key expires (UTC). None means no expiration."},"is_active":{"type":"boolean","title":"Is Active","description":"Whether the API key is active.","default":true},"last_used_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Used At","description":"Timestamp when the API key was last used (UTC)."}},"type":"object","required":["key_id","key","created_at"],"title":"ApiKey","description":"Represents an API key for a user."}}},"paths":{"/users/me":{"get":{"summary":"Get Current User","description":"Get current user information","operationId":"get_current_user_users_me_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}}}}}}} ``` ## Accept Terms > Record that the current user has accepted the terms of service. ```json {"openapi":"3.1.0","info":{"title":"Codeset API","version":"1.0.0"},"servers":[{"url":"/api/v1"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","description":"Bearer token for API authentication","scheme":"bearer"}},"schemas":{"User":{"properties":{"user_id":{"type":"string","title":"User Id","description":"Unique identifier for the user."},"name":{"type":"string","title":"Name","description":"Display name of the user."},"email":{"type":"string","title":"Email","description":"Email address of the user."},"github_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Github Id","description":"GitHub user ID for OAuth authentication."},"github_login":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Github Login","description":"GitHub username (login) for matching app installations."},"api_keys":{"items":{"$ref":"#/components/schemas/ApiKey"},"type":"array","title":"Api Keys","description":"List of API keys associated with this user."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Timestamp when the user was created (UTC)."},"last_login_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Login At","description":"Timestamp of the user's last login (UTC)."},"is_active":{"type":"boolean","title":"Is Active","description":"Whether the user account is active.","default":true},"terms_accepted_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Terms Accepted At","description":"When the user last accepted the terms of service (UTC). None if not accepted."}},"type":"object","required":["user_id","name","email","created_at"],"title":"User","description":"Represents a user in the system."},"ApiKey":{"properties":{"key_id":{"type":"string","title":"Key Id","description":"Unique identifier for the API key."},"key":{"type":"string","title":"Key","description":"The actual API key value."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Optional name for the API key."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Timestamp when the API key was created (UTC)."},"expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expires At","description":"Timestamp when the API key expires (UTC). None means no expiration."},"is_active":{"type":"boolean","title":"Is Active","description":"Whether the API key is active.","default":true},"last_used_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Used At","description":"Timestamp when the API key was last used (UTC)."}},"type":"object","required":["key_id","key","created_at"],"title":"ApiKey","description":"Represents an API key for a user."}}},"paths":{"/users/me/accept-terms":{"post":{"summary":"Accept Terms","description":"Record that the current user has accepted the terms of service.","operationId":"accept_terms_users_me_accept_terms_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}}}}}}} ``` ## Create Api Key > Create a new API key for the current user ```json {"openapi":"3.1.0","info":{"title":"Codeset API","version":"1.0.0"},"servers":[{"url":"/api/v1"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","description":"Bearer token for API authentication","scheme":"bearer"}},"schemas":{"ApiKeyCreateRequest":{"properties":{"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Optional name for the API key."}},"type":"object","title":"ApiKeyCreateRequest","description":"Request to create a new API key for a user."},"ApiKeyCreateResponse":{"properties":{"api_key":{"$ref":"#/components/schemas/ApiKey","description":"The newly created API key object."}},"type":"object","required":["api_key"],"title":"ApiKeyCreateResponse","description":"Response for creating an API key."},"ApiKey":{"properties":{"key_id":{"type":"string","title":"Key Id","description":"Unique identifier for the API key."},"key":{"type":"string","title":"Key","description":"The actual API key value."},"name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Name","description":"Optional name for the API key."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Timestamp when the API key was created (UTC)."},"expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expires At","description":"Timestamp when the API key expires (UTC). None means no expiration."},"is_active":{"type":"boolean","title":"Is Active","description":"Whether the API key is active.","default":true},"last_used_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Used At","description":"Timestamp when the API key was last used (UTC)."}},"type":"object","required":["key_id","key","created_at"],"title":"ApiKey","description":"Represents an API key for a user."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/users/me/api-keys":{"post":{"summary":"Create Api Key","description":"Create a new API key for the current user","operationId":"create_api_key_users_me_api_keys_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyCreateRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyCreateResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## Revoke Api Key > Revoke an API key for the current user ```json {"openapi":"3.1.0","info":{"title":"Codeset API","version":"1.0.0"},"servers":[{"url":"/api/v1"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","description":"Bearer token for API authentication","scheme":"bearer"}},"schemas":{"ApiKeyRevokeRequest":{"properties":{"key_id":{"type":"string","title":"Key Id","description":"The ID of the API key to revoke."}},"type":"object","required":["key_id"],"title":"ApiKeyRevokeRequest","description":"Request to revoke an API key."},"ApiKeyRevokeResponse":{"properties":{"message":{"type":"string","title":"Message","description":"Success message."},"revoked_key_id":{"type":"string","title":"Revoked Key Id","description":"The ID of the revoked API key."}},"type":"object","required":["message","revoked_key_id"],"title":"ApiKeyRevokeResponse","description":"Response for revoking an API key."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/users/me/api-keys":{"delete":{"summary":"Revoke Api Key","description":"Revoke an API key for the current user","operationId":"revoke_api_key_users_me_api_keys_delete","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyRevokeRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiKeyRevokeResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## List Datasets > List available datasets ```json {"openapi":"3.1.0","info":{"title":"Codeset API","version":"1.0.0"},"servers":[{"url":"/api/v1"}],"paths":{"/datasets":{"get":{"summary":"List Datasets","description":"List available datasets","operationId":"list_datasets_datasets_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"items":{"$ref":"#/components/schemas/Dataset"},"type":"array","title":"Response List Datasets Datasets Get"}}}}}}}},"components":{"schemas":{"Dataset":{"properties":{"name":{"type":"string","title":"Name","description":"Unique name of the dataset."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"A brief description of the dataset."},"sample_count":{"type":"integer","title":"Sample Count","description":"Number of samples in the dataset."},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At","description":"Timestamp when the dataset was first created (UTC)."}},"type":"object","required":["name","sample_count"],"title":"Dataset","description":"Information about a dataset."}}}} ``` ## List Samples > List available samples with optional pagination, optionally filtered by dataset ```json {"openapi":"3.1.0","info":{"title":"Codeset API","version":"1.0.0"},"servers":[{"url":"/api/v1"}],"paths":{"/samples":{"get":{"summary":"List Samples","description":"List available samples with optional pagination, optionally filtered by dataset","operationId":"list_samples_samples_get","parameters":[{"name":"dataset","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter samples by dataset name","title":"Dataset"},"description":"Filter samples by dataset name"},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Search for samples by instance_id","title":"Search"},"description":"Search for samples by instance_id"},{"name":"page","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"description":"Page number (1-based). If not provided, returns all samples","title":"Page"},"description":"Page number (1-based). If not provided, returns all samples"},{"name":"page_size","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":100,"minimum":1},{"type":"null"}],"description":"Number of samples per page (max 100). If not provided, returns all samples","title":"Page Size"},"description":"Number of samples per page (max 100). If not provided, returns all samples"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SampleListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"SampleListResponse":{"properties":{"samples":{"items":{"$ref":"#/components/schemas/Sample"},"type":"array","title":"Samples","description":"List of samples for the current page."},"total_count":{"type":"integer","title":"Total Count","description":"Total number of samples available."},"page":{"type":"integer","title":"Page","description":"Current page number (1-based)."},"page_size":{"type":"integer","title":"Page Size","description":"Number of samples per page."},"has_more":{"type":"boolean","title":"Has More","description":"Indicates if more pages of results are available."}},"type":"object","required":["samples","total_count","page","page_size","has_more"],"title":"SampleListResponse","description":"Response for listing samples with pagination."},"Sample":{"properties":{"sample_id":{"type":"string","title":"Sample Id","description":"Unique identifier for the sample (e.g., 'traccar-1')."},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description","description":"A brief description of the sample."},"language":{"type":"string","title":"Language","description":"Primary programming language of the sample."},"verifier":{"$ref":"#/components/schemas/VerificationTool","description":"The type of verifier used for this sample."},"dataset":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Dataset","description":"Dataset name for the sample."},"version":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Version","description":"Version number of the sample."},"version_description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Version Description","description":"Description of this version."},"latest":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Latest","description":"Whether this is the latest version."},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At","description":"Timestamp when the sample was created (UTC)."},"instance_id":{"type":"string","title":"Instance Id","description":"Instance identifier for the sample (e.g., 'psf__requests-1234')."},"repo":{"type":"string","title":"Repo","description":"Repository full name for the sample (e.g., 'psf/requests')."},"base_commit":{"type":"string","title":"Base Commit","description":"Base commit hash for the sample."},"patch":{"type":"string","title":"Patch","description":"Code patch (diff) that fixes the bug for the sample."},"non_code_patch":{"type":"string","title":"Non Code Patch","description":"Non-code patch for the sample."},"test_patch":{"type":"string","title":"Test Patch","description":"Test patch (diff) for the sample."},"problem_statement":{"type":"string","title":"Problem Statement","description":"Problem statement for the sample (issue title + body)."},"hints_text":{"type":"string","title":"Hints Text","description":"Hints text for the sample (concatenated issue comments)."},"environment_setup_commit":{"type":"string","title":"Environment Setup Commit","description":"Environment setup commit hash for the sample."},"fail_to_pass":{"items":{"type":"string"},"type":"array","title":"Fail To Pass","description":"List of test names that changed from FAIL to PASS."},"pass_to_pass":{"items":{"type":"string"},"type":"array","title":"Pass To Pass","description":"List of test names that remained PASS to PASS."},"fail_to_fail":{"items":{"type":"string"},"type":"array","title":"Fail To Fail","description":"List of test names that remained FAIL to FAIL."}},"type":"object","required":["sample_id","language","verifier","instance_id","repo","base_commit","patch","non_code_patch","test_patch","problem_statement","hints_text","environment_setup_commit","fail_to_pass","pass_to_pass","fail_to_fail"],"title":"Sample","description":"Information about a software engineering task sample."},"VerificationTool":{"type":"string","enum":["test_suite","static_analysis","linter","custom"],"title":"VerificationTool","description":"Type of verification tool used."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}} ``` ## Download Sample > Download the gz file for a specific sample ```json {"openapi":"3.1.0","info":{"title":"Codeset API","version":"1.0.0"},"servers":[{"url":"/api/v1"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","description":"Bearer token for API authentication","scheme":"bearer"}},"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/samples/{dataset}/{sample_id}/download":{"get":{"summary":"Download Sample","description":"Download the gz file for a specific sample","operationId":"download_sample_samples__dataset___sample_id__download_get","parameters":[{"name":"dataset","in":"path","required":true,"schema":{"type":"string","title":"Dataset"}},{"name":"sample_id","in":"path","required":true,"schema":{"type":"string","title":"Sample Id"}},{"name":"version","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Version"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## List Sessions > List environment sessions ```json {"openapi":"3.1.0","info":{"title":"Codeset API","version":"1.0.0"},"servers":[{"url":"/api/v1"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","description":"Bearer token for API authentication","scheme":"bearer"}},"schemas":{"SessionListResponse":{"properties":{"sessions":{"items":{"$ref":"#/components/schemas/Session"},"type":"array","title":"Sessions"},"total_count":{"type":"integer","title":"Total Count","description":"Total number of sessions returned."},"has_more":{"type":"boolean","title":"Has More","description":"Indicates if more pages of results are available."}},"type":"object","required":["sessions","total_count","has_more"],"title":"SessionListResponse","description":"Response for listing sessions."},"Session":{"properties":{"session_id":{"type":"string","title":"Session Id","description":"Unique identifier for the session."},"user_id":{"type":"string","title":"User Id","description":"User ID who owns this session."},"dataset":{"type":"string","title":"Dataset","description":"Dataset name for the sample."},"sample_id":{"type":"string","title":"Sample Id","description":"Identifier of the sample being used for the session."},"status":{"$ref":"#/components/schemas/SessionStatus","description":"Current status of the session."},"requested_at":{"type":"string","format":"date-time","title":"Requested At","description":"Timestamp when the session was requested (UTC)."},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At","description":"Timestamp when the container became ready and billing started (UTC)."},"expires_at":{"type":"string","format":"date-time","title":"Expires At","description":"Timestamp when the session will expire (UTC)."},"duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Duration Seconds","description":"Duration of the session in seconds."},"container_info":{"anyOf":[{"$ref":"#/components/schemas/ContainerInfo"},{"type":"null"}],"description":"Container information for this session."},"error":{"anyOf":[{"$ref":"#/components/schemas/ErrorInfo"},{"type":"null"}],"description":"Error details if the session failed."}},"type":"object","required":["session_id","user_id","dataset","sample_id","status","requested_at","expires_at"],"title":"Session","description":"Represents a session for multi-turn interactions."},"SessionStatus":{"type":"string","enum":["creating","ready","error","closed","terminated"],"title":"SessionStatus","description":"Status of a session."},"ContainerInfo":{"properties":{"container_name":{"type":"string","title":"Container Name","description":"Name of the Cloud Run service."},"service_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Service Url","description":"URL of the Cloud Run service."},"sample_id":{"type":"string","title":"Sample Id","description":"Sample ID of the container."},"status":{"type":"string","title":"Status","description":"Status of the container."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Timestamp when the container was created (UTC)."},"expires_at":{"type":"string","format":"date-time","title":"Expires At","description":"Timestamp when the container will expire (UTC)."},"location":{"type":"string","title":"Location","description":"Cloud Run region where the container is deployed (e.g., 'europe-west1')."}},"type":"object","required":["container_name","service_url","sample_id","status","created_at","expires_at","location"],"title":"ContainerInfo","description":"Information about a container."},"ErrorInfo":{"properties":{"code":{"type":"string","title":"Code","description":"A unique error code for programmatic handling."},"message":{"type":"string","title":"Message","description":"A human-readable error message."}},"type":"object","required":["code","message"],"title":"ErrorInfo","description":"Details about an error that occurred during job processing."}}},"paths":{"/sessions":{"get":{"summary":"List Sessions","description":"List environment sessions","operationId":"list_sessions_sessions_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionListResponse"}}}}}}}}} ``` ## Create Session > Create a new session ```json {"openapi":"3.1.0","info":{"title":"Codeset API","version":"1.0.0"},"servers":[{"url":"/api/v1"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","description":"Bearer token for API authentication","scheme":"bearer"}},"schemas":{"SessionCreateRequest":{"properties":{"dataset":{"type":"string","title":"Dataset","description":"Dataset name for the sample."},"sample_id":{"type":"string","title":"Sample Id","description":"Identifier of the sample to use for this session."},"ttl_minutes":{"type":"integer","title":"Ttl Minutes","description":"Time to live for the session in minutes (default: 30).","default":30}},"type":"object","required":["dataset","sample_id"],"title":"SessionCreateRequest","description":"Request to create a new session."},"SessionCreateResponse":{"properties":{"session_id":{"type":"string","title":"Session Id","description":"Unique identifier for the created session."},"status":{"$ref":"#/components/schemas/SessionStatus","description":"Initial status of the session."},"expires_at":{"type":"string","format":"date-time","title":"Expires At","description":"Timestamp when the session will expire (UTC)."}},"type":"object","required":["session_id","status","expires_at"],"title":"SessionCreateResponse","description":"Response for creating a session."},"SessionStatus":{"type":"string","enum":["creating","ready","error","closed","terminated"],"title":"SessionStatus","description":"Status of a session."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/sessions":{"post":{"summary":"Create Session","description":"Create a new session","operationId":"create_session_sessions_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionCreateRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionCreateResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## Get Session > Get session details ```json {"openapi":"3.1.0","info":{"title":"Codeset API","version":"1.0.0"},"servers":[{"url":"/api/v1"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","description":"Bearer token for API authentication","scheme":"bearer"}},"schemas":{"Session":{"properties":{"session_id":{"type":"string","title":"Session Id","description":"Unique identifier for the session."},"user_id":{"type":"string","title":"User Id","description":"User ID who owns this session."},"dataset":{"type":"string","title":"Dataset","description":"Dataset name for the sample."},"sample_id":{"type":"string","title":"Sample Id","description":"Identifier of the sample being used for the session."},"status":{"$ref":"#/components/schemas/SessionStatus","description":"Current status of the session."},"requested_at":{"type":"string","format":"date-time","title":"Requested At","description":"Timestamp when the session was requested (UTC)."},"created_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At","description":"Timestamp when the container became ready and billing started (UTC)."},"expires_at":{"type":"string","format":"date-time","title":"Expires At","description":"Timestamp when the session will expire (UTC)."},"duration_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Duration Seconds","description":"Duration of the session in seconds."},"container_info":{"anyOf":[{"$ref":"#/components/schemas/ContainerInfo"},{"type":"null"}],"description":"Container information for this session."},"error":{"anyOf":[{"$ref":"#/components/schemas/ErrorInfo"},{"type":"null"}],"description":"Error details if the session failed."}},"type":"object","required":["session_id","user_id","dataset","sample_id","status","requested_at","expires_at"],"title":"Session","description":"Represents a session for multi-turn interactions."},"SessionStatus":{"type":"string","enum":["creating","ready","error","closed","terminated"],"title":"SessionStatus","description":"Status of a session."},"ContainerInfo":{"properties":{"container_name":{"type":"string","title":"Container Name","description":"Name of the Cloud Run service."},"service_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Service Url","description":"URL of the Cloud Run service."},"sample_id":{"type":"string","title":"Sample Id","description":"Sample ID of the container."},"status":{"type":"string","title":"Status","description":"Status of the container."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Timestamp when the container was created (UTC)."},"expires_at":{"type":"string","format":"date-time","title":"Expires At","description":"Timestamp when the container will expire (UTC)."},"location":{"type":"string","title":"Location","description":"Cloud Run region where the container is deployed (e.g., 'europe-west1')."}},"type":"object","required":["container_name","service_url","sample_id","status","created_at","expires_at","location"],"title":"ContainerInfo","description":"Information about a container."},"ErrorInfo":{"properties":{"code":{"type":"string","title":"Code","description":"A unique error code for programmatic handling."},"message":{"type":"string","title":"Message","description":"A human-readable error message."}},"type":"object","required":["code","message"],"title":"ErrorInfo","description":"Details about an error that occurred during job processing."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/sessions/{session_id}":{"get":{"summary":"Get Session","description":"Get session details","operationId":"get_session_sessions__session_id__get","parameters":[{"name":"session_id","in":"path","required":true,"schema":{"type":"string","title":"Session Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Session"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## Close Session > Close/delete an environment session ```json {"openapi":"3.1.0","info":{"title":"Codeset API","version":"1.0.0"},"servers":[{"url":"/api/v1"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","description":"Bearer token for API authentication","scheme":"bearer"}},"schemas":{"SessionDeleteResponse":{"properties":{"message":{"type":"string","title":"Message","description":"Success message confirming session deletion"},"duration_seconds":{"type":"number","title":"Duration Seconds","description":"Duration of the session in seconds."}},"type":"object","required":["message","duration_seconds"],"title":"SessionDeleteResponse","description":"Response model for session deletion."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/sessions/{session_id}":{"delete":{"summary":"Close Session","description":"Close/delete an environment session","operationId":"close_session_sessions__session_id__delete","parameters":[{"name":"session_id","in":"path","required":true,"schema":{"type":"string","title":"Session Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SessionDeleteResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## Execute Command > Start command execution in an environment (async) ```json {"openapi":"3.1.0","info":{"title":"Codeset API","version":"1.0.0"},"servers":[{"url":"/api/v1"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","description":"Bearer token for API authentication","scheme":"bearer"}},"schemas":{"ExecRequest":{"properties":{"command":{"type":"string","title":"Command","description":"The bash command to execute."},"command_timeout":{"type":"integer","title":"Command Timeout","description":"Timeout for command execution in seconds (default: 300).","default":300}},"type":"object","required":["command"],"title":"ExecRequest","description":"Request to execute a bash command in a session."},"ExecStartResponse":{"properties":{"interaction_id":{"type":"string","title":"Interaction Id","description":"Unique identifier for the interaction."},"status":{"type":"string","title":"Status","description":"Status of the interaction: 'pending', 'processing', 'completed', or 'failed'."}},"type":"object","required":["interaction_id","status"],"title":"ExecStartResponse","description":"Response for starting command execution (async)."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/sessions/{session_id}/exec":{"post":{"summary":"Execute Command","description":"Start command execution in an environment (async)","operationId":"execute_command_sessions__session_id__exec_post","parameters":[{"name":"session_id","in":"path","required":true,"schema":{"type":"string","title":"Session Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExecRequest"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExecStartResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## Get Interaction > Get interaction details by ID ```json {"openapi":"3.1.0","info":{"title":"Codeset API","version":"1.0.0"},"servers":[{"url":"/api/v1"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","description":"Bearer token for API authentication","scheme":"bearer"}},"schemas":{"ExecCommandInteraction":{"properties":{"interaction_id":{"type":"string","title":"Interaction Id","description":"Unique identifier for the interaction."},"session_id":{"type":"string","title":"Session Id","description":"Session identifier for this interaction."},"interaction_type":{"type":"string","const":"exec_command","title":"Interaction Type","default":"exec_command"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Timestamp when the interaction was created (UTC)."},"exit_code":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Exit Code","description":"Exit code of the interaction."},"stdout":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stdout","description":"Standard output from the interaction."},"stderr":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stderr","description":"Standard error from the interaction."},"execution_time_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Execution Time Seconds","description":"Execution time in seconds."},"success":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Success","description":"Whether the interaction was successful."},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message","description":"Additional message about the interaction result."},"command":{"type":"string","title":"Command","description":"Command that was executed."},"command_timeout":{"type":"integer","title":"Command Timeout","description":"Timeout for command execution in seconds.","default":300}},"type":"object","required":["interaction_id","session_id","created_at","command"],"title":"ExecCommandInteraction","description":"Interaction for executing a command in the environment."},"StringReplaceInteraction":{"properties":{"interaction_id":{"type":"string","title":"Interaction Id","description":"Unique identifier for the interaction."},"session_id":{"type":"string","title":"Session Id","description":"Session identifier for this interaction."},"interaction_type":{"type":"string","const":"string_replace","title":"Interaction Type","default":"string_replace"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Timestamp when the interaction was created (UTC)."},"exit_code":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Exit Code","description":"Exit code of the interaction."},"stdout":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stdout","description":"Standard output from the interaction."},"stderr":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stderr","description":"Standard error from the interaction."},"execution_time_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Execution Time Seconds","description":"Execution time in seconds."},"success":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Success","description":"Whether the interaction was successful."},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message","description":"Additional message about the interaction result."},"file_path":{"type":"string","title":"File Path","description":"Path to the file where replacement was performed."},"str_to_replace":{"type":"string","title":"Str To Replace","description":"String that was replaced."},"str_to_insert":{"type":"string","title":"Str To Insert","description":"String that was inserted as replacement."}},"type":"object","required":["interaction_id","session_id","created_at","file_path","str_to_replace","str_to_insert"],"title":"StringReplaceInteraction","description":"Interaction for replacing a string in a file."},"FileUploadInteraction":{"properties":{"interaction_id":{"type":"string","title":"Interaction Id","description":"Unique identifier for the interaction."},"session_id":{"type":"string","title":"Session Id","description":"Session identifier for this interaction."},"interaction_type":{"type":"string","const":"file_upload","title":"Interaction Type","default":"file_upload"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Timestamp when the interaction was created (UTC)."},"exit_code":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Exit Code","description":"Exit code of the interaction."},"stdout":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stdout","description":"Standard output from the interaction."},"stderr":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stderr","description":"Standard error from the interaction."},"execution_time_seconds":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Execution Time Seconds","description":"Execution time in seconds."},"success":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Success","description":"Whether the interaction was successful."},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message","description":"Additional message about the interaction result."},"file_path":{"type":"string","title":"File Path","description":"Destination path for the uploaded file."},"size_bytes":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Size Bytes","description":"Size of the uploaded file in bytes."},"make_executable":{"type":"boolean","title":"Make Executable","description":"Whether the file was made executable.","default":false}},"type":"object","required":["interaction_id","session_id","created_at","file_path"],"title":"FileUploadInteraction","description":"Interaction for uploading a file to the environment."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/sessions/{session_id}/interactions/{interaction_id}":{"get":{"summary":"Get Interaction","description":"Get interaction details by ID","operationId":"get_interaction_sessions__session_id__interactions__interaction_id__get","parameters":[{"name":"interaction_id","in":"path","required":true,"schema":{"type":"string","title":"Interaction Id"}},{"name":"session_id","in":"path","required":true,"schema":{"type":"string","title":"Session Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/ExecCommandInteraction"},{"$ref":"#/components/schemas/StringReplaceInteraction"},{"$ref":"#/components/schemas/FileUploadInteraction"}],"title":"Response Get Interaction Sessions Session Id Interactions Interaction Id Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## String Replace > Replace a string in a file within the session environment ```json {"openapi":"3.1.0","info":{"title":"Codeset API","version":"1.0.0"},"servers":[{"url":"/api/v1"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","description":"Bearer token for API authentication","scheme":"bearer"}},"schemas":{"StringReplaceRequest":{"properties":{"file_path":{"type":"string","title":"File Path","description":"Path to the file where replacement should be performed."},"str_to_replace":{"type":"string","title":"Str To Replace","description":"String to be replaced."},"str_to_insert":{"type":"string","title":"Str To Insert","description":"String to insert as replacement."}},"type":"object","required":["file_path","str_to_replace","str_to_insert"],"title":"StringReplaceRequest","description":"Request to perform string replacement in a file."},"StringReplaceResponse":{"properties":{"success":{"type":"boolean","title":"Success","description":"Whether the string replacement was successful."},"message":{"type":"string","title":"Message","description":"Details about the string replacement operation."}},"type":"object","required":["success","message"],"title":"StringReplaceResponse","description":"Response for string replacement operation."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/sessions/{session_id}/str_replace":{"post":{"summary":"String Replace","description":"Replace a string in a file within the session environment","operationId":"string_replace_sessions__session_id__str_replace_post","parameters":[{"name":"session_id","in":"path","required":true,"schema":{"type":"string","title":"Session Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StringReplaceRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StringReplaceResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## Upload File > Upload a file to the session environment ```json {"openapi":"3.1.0","info":{"title":"Codeset API","version":"1.0.0"},"servers":[{"url":"/api/v1"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","description":"Bearer token for API authentication","scheme":"bearer"}},"schemas":{"FileUploadRequest":{"properties":{"file_path":{"type":"string","title":"File Path","description":"Destination path for the file inside the container."},"content_base64":{"type":"string","title":"Content Base64","description":"Base64-encoded file content."},"make_executable":{"type":"boolean","title":"Make Executable","description":"Whether to make the file executable (chmod +x).","default":false}},"type":"object","required":["file_path","content_base64"],"title":"FileUploadRequest","description":"Request to upload a file to the session environment."},"FileUploadResponse":{"properties":{"success":{"type":"boolean","title":"Success","description":"Whether the file upload was successful."},"message":{"type":"string","title":"Message","description":"Details about the file upload operation."},"file_path":{"type":"string","title":"File Path","description":"Destination path where the file was written."},"size_bytes":{"type":"integer","title":"Size Bytes","description":"Size of the uploaded file in bytes."}},"type":"object","required":["success","message","file_path","size_bytes"],"title":"FileUploadResponse","description":"Response for file upload operation."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/sessions/{session_id}/upload":{"post":{"summary":"Upload File","description":"Upload a file to the session environment","operationId":"upload_file_sessions__session_id__upload_post","parameters":[{"name":"session_id","in":"path","required":true,"schema":{"type":"string","title":"Session Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileUploadRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FileUploadResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## Start Verification > Start verification (oracle) in a session - async ```json {"openapi":"3.1.0","info":{"title":"Codeset API","version":"1.0.0"},"servers":[{"url":"/api/v1"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","description":"Bearer token for API authentication","scheme":"bearer"}},"schemas":{"VerifyStartResponse":{"properties":{"job_id":{"type":"string","title":"Job Id","description":"Unique identifier for the verification job."},"status":{"$ref":"#/components/schemas/JobStatus","description":"Initial status of the verification job."},"started_at":{"type":"string","format":"date-time","title":"Started At","description":"Timestamp when verification started (UTC)."}},"type":"object","required":["job_id","status","started_at"],"title":"VerifyStartResponse","description":"Response for starting verification (async)."},"JobStatus":{"type":"string","enum":["pending","starting","running","completed","error","cancelled"],"title":"JobStatus","description":"Status of a verification job."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/sessions/{session_id}/verify":{"post":{"summary":"Start Verification","description":"Start verification (oracle) in a session - async","operationId":"start_verification_sessions__session_id__verify_post","parameters":[{"name":"session_id","in":"path","required":true,"schema":{"type":"string","title":"Session Id"}}],"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerifyStartResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## Get Verification Job > Get a verification job, including the result if it's completed ```json {"openapi":"3.1.0","info":{"title":"Codeset API","version":"1.0.0"},"servers":[{"url":"/api/v1"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","description":"Bearer token for API authentication","scheme":"bearer"}},"schemas":{"VerificationJob":{"properties":{"job_id":{"type":"string","title":"Job Id","description":"Unique identifier for the job."},"sample_id":{"type":"string","title":"Sample Id","description":"Identifier of the sample being used for verification."},"session_id":{"type":"string","title":"Session Id","description":"Session identifier for this job."},"status":{"$ref":"#/components/schemas/JobStatus","description":"Current status of the job."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Timestamp when the job was created (UTC)."},"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At","description":"Timestamp when the job processing started (UTC)."},"completed_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Completed At","description":"Timestamp when the job completed (UTC)."},"result":{"anyOf":[{"oneOf":[{"$ref":"#/components/schemas/TestSuiteResult"}],"discriminator":{"propertyName":"tool","mapping":{"test_suite":"#/components/schemas/TestSuiteResult"}}},{"type":"null"}],"title":"Result","description":"The result of the verification. Available when status is 'completed'."},"error":{"anyOf":[{"$ref":"#/components/schemas/ErrorInfo"},{"type":"null"}],"description":"Error details if the job failed with an 'error' status."},"container_info":{"anyOf":[{"$ref":"#/components/schemas/ContainerInfo"},{"type":"null"}],"description":"Container information for this job."}},"type":"object","required":["job_id","sample_id","session_id","status","created_at"],"title":"VerificationJob","description":"Represents a single verification job, the core resource of the API."},"JobStatus":{"type":"string","enum":["pending","starting","running","completed","error","cancelled"],"title":"JobStatus","description":"Status of a verification job."},"TestSuiteResult":{"properties":{"tool":{"type":"string","const":"test_suite","title":"Tool","default":"test_suite"},"is_success":{"type":"boolean","title":"Is Success","description":"Overall success status of the verification."},"execution_duration_seconds":{"type":"number","title":"Execution Duration Seconds","description":"Total execution time for the verification step."},"total":{"type":"integer","title":"Total","description":"Total number of tests executed."},"passed":{"type":"integer","title":"Passed","description":"Number of tests that passed."},"failed":{"type":"integer","title":"Failed","description":"Number of tests that failed."},"skipped":{"type":"integer","title":"Skipped","description":"Number of tests that were skipped."},"passes":{"items":{},"type":"array","title":"Passes","description":"A list of passing tests with their details.","default":[]},"failures":{"items":{},"type":"array","title":"Failures","description":"A list of failed tests with their details.","default":[]},"skips":{"items":{},"type":"array","title":"Skips","description":"A list of skipped/ignored tests with their details.","default":[]},"stdout":{"type":"string","title":"Stdout","description":"Standard output from the verifier.","default":"PLACE_HOLDER"},"stderr":{"type":"string","title":"Stderr","description":"Standard error from the verifier.","default":"PLACE_HOLDER"}},"type":"object","required":["is_success","execution_duration_seconds","total","passed","failed","skipped"],"title":"TestSuiteResult","description":"Result from a test suite verifier."},"ErrorInfo":{"properties":{"code":{"type":"string","title":"Code","description":"A unique error code for programmatic handling."},"message":{"type":"string","title":"Message","description":"A human-readable error message."}},"type":"object","required":["code","message"],"title":"ErrorInfo","description":"Details about an error that occurred during job processing."},"ContainerInfo":{"properties":{"container_name":{"type":"string","title":"Container Name","description":"Name of the Cloud Run service."},"service_url":{"type":"string","maxLength":2083,"minLength":1,"format":"uri","title":"Service Url","description":"URL of the Cloud Run service."},"sample_id":{"type":"string","title":"Sample Id","description":"Sample ID of the container."},"status":{"type":"string","title":"Status","description":"Status of the container."},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"Timestamp when the container was created (UTC)."},"expires_at":{"type":"string","format":"date-time","title":"Expires At","description":"Timestamp when the container will expire (UTC)."},"location":{"type":"string","title":"Location","description":"Cloud Run region where the container is deployed (e.g., 'europe-west1')."}},"type":"object","required":["container_name","service_url","sample_id","status","created_at","expires_at","location"],"title":"ContainerInfo","description":"Information about a container."},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/sessions/{session_id}/verify/{job_id}":{"get":{"summary":"Get Verification Job","description":"Get a verification job, including the result if it's completed","operationId":"get_verification_job_sessions__session_id__verify__job_id__get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}},{"name":"session_id","in":"path","required":true,"schema":{"type":"string","title":"Session Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/VerificationJob"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## Get User Balance > Get user's money balance ```json {"openapi":"3.1.0","info":{"title":"Codeset API","version":"1.0.0"},"servers":[{"url":"/api/v1"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","description":"Bearer token for API authentication","scheme":"bearer"}},"schemas":{"UserCredits":{"properties":{"user_id":{"type":"string","title":"User Id","description":"User ID"},"balance":{"type":"integer","title":"Balance","description":"Current balance in cents","default":0},"total_deposited":{"type":"integer","title":"Total Deposited","description":"Total money ever deposited in cents","default":0},"total_spent":{"type":"integer","title":"Total Spent","description":"Total money ever spent in cents","default":0},"stripe_customer_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stripe Customer Id","description":"Stripe customer ID"},"last_updated":{"type":"string","format":"date-time","title":"Last Updated","description":"Last time balance was updated"}},"type":"object","required":["user_id","last_updated"],"title":"UserCredits","description":"User's money balance and billing information"}}},"paths":{"/billing/balance":{"get":{"summary":"Get User Balance","description":"Get user's money balance","operationId":"get_user_balance_billing_balance_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserCredits"}}}}}}}}} ``` ## Get Pricing Info > Get current pricing information ```json {"openapi":"3.1.0","info":{"title":"Codeset API","version":"1.0.0"},"servers":[{"url":"/api/v1"}],"paths":{"/billing/pricing":{"get":{"summary":"Get Pricing Info","description":"Get current pricing information","operationId":"get_pricing_info_billing_pricing_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Get Pricing Info Billing Pricing Get"}}}}}}}}} ``` ## Deposit Money > Create a payment intent for money deposit ```json {"openapi":"3.1.0","info":{"title":"Codeset API","version":"1.0.0"},"servers":[{"url":"/api/v1"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","description":"Bearer token for API authentication","scheme":"bearer"}},"schemas":{"MoneyDepositRequest":{"properties":{"amount_cents":{"type":"integer","minimum":100,"title":"Amount Cents","description":"Amount to deposit in cents"},"currency":{"type":"string","title":"Currency","description":"Currency for payment","default":"usd"}},"type":"object","required":["amount_cents"],"title":"MoneyDepositRequest","description":"Request to deposit money"},"MoneyDepositResponse":{"properties":{"checkout_url":{"type":"string","title":"Checkout Url","description":"Stripe checkout URL for payment"},"amount_cents":{"type":"integer","title":"Amount Cents","description":"Amount being deposited in cents"},"currency":{"type":"string","title":"Currency","description":"Currency"}},"type":"object","required":["checkout_url","amount_cents","currency"],"title":"MoneyDepositResponse","description":"Response for money deposit"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/billing/deposit":{"post":{"summary":"Deposit Money","description":"Create a payment intent for money deposit","operationId":"deposit_money_billing_deposit_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MoneyDepositRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MoneyDepositResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## Stripe Webhook > Handle Stripe webhook events ```json {"openapi":"3.1.0","info":{"title":"Codeset API","version":"1.0.0"},"servers":[{"url":"/api/v1"}],"paths":{"/billing/webhook":{"post":{"summary":"Stripe Webhook","description":"Handle Stripe webhook events","operationId":"stripe_webhook_billing_webhook_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"additionalProperties":true,"type":"object","title":"Response Stripe Webhook Billing Webhook Post"}}}}}}}}} ``` ## Get Usage History > Get complete usage history for the current user ```json {"openapi":"3.1.0","info":{"title":"Codeset API","version":"1.0.0"},"servers":[{"url":"/api/v1"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","description":"Bearer token for API authentication","scheme":"bearer"}},"schemas":{"UsageHistory":{"properties":{"current_balance_cents":{"type":"integer","title":"Current Balance Cents","description":"Current balance in cents"},"total_deposits_cents":{"type":"integer","title":"Total Deposits Cents","description":"Total amount deposited"},"total_usage_cents":{"type":"integer","title":"Total Usage Cents","description":"Total amount used"},"transactions":{"items":{"$ref":"#/components/schemas/UsageTransaction"},"type":"array","title":"Transactions","description":"List of transactions for current page"},"summary":{"additionalProperties":true,"type":"object","title":"Summary","description":"Usage summary statistics"},"pagination":{"additionalProperties":true,"type":"object","title":"Pagination","description":"Pagination information"}},"type":"object","required":["current_balance_cents","total_deposits_cents","total_usage_cents","transactions","summary","pagination"],"title":"UsageHistory","description":"Complete usage history for a user"},"UsageTransaction":{"properties":{"id":{"type":"string","title":"Id","description":"Unique transaction identifier"},"type":{"type":"string","enum":["deposit","refund","session_usage","agent_job_usage","agent_job_refund"],"title":"Type","description":"Type of transaction"},"amount_cents":{"type":"integer","title":"Amount Cents","description":"Amount in cents (positive for deposits/refunds, negative for usage)"},"description":{"type":"string","title":"Description","description":"Description of the transaction"},"created_at":{"type":"string","format":"date-time","title":"Created At","description":"When the transaction occurred"},"session_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Session Id","description":"Session ID if this is session usage"},"duration_minutes":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Duration Minutes","description":"Session duration if applicable"},"job_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Job Id","description":"Agent job ID if this is agent job usage or refund"}},"type":"object","required":["id","type","amount_cents","description","created_at"],"title":"UsageTransaction","description":"Represents a usage transaction (deposit, refund, or spending)"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/billing/usage":{"get":{"summary":"Get Usage History","description":"Get complete usage history for the current user","operationId":"get_usage_history_billing_usage_get","parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"integer","minimum":1,"description":"Page number (1-based)","default":1,"title":"Page"},"description":"Page number (1-based)"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Items per page (max 100)","default":25,"title":"Limit"},"description":"Items per page (max 100)"},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Include only transactions on or after this date (UTC).","title":"Start Date"},"description":"Include only transactions on or after this date (UTC)."},{"name":"end_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date"},{"type":"null"}],"description":"Include only transactions on or before this date (UTC).","title":"End Date"},"description":"Include only transactions on or before this date (UTC)."},{"name":"transaction_types","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"description":"Filter by transaction type(s): deposit, usage, charge, refund, agent_job_usage, agent_job_refund.","title":"Transaction Types"},"description":"Filter by transaction type(s): deposit, usage, charge, refund, agent_job_usage, agent_job_refund."},{"name":"max_items","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","maximum":10000,"minimum":1},{"type":"null"}],"description":"Max transactions to load (default: all). Ignored when start_date or end_date is set.","title":"Max Items"},"description":"Max transactions to load (default: all). Ignored when start_date or end_date is set."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UsageHistory"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## GET /agent-jobs > List Agent Jobs ```json {"openapi":"3.1.0","info":{"title":"Codeset API","version":"1.0.0"},"servers":[{"url":"/api/v1"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","description":"Bearer token for API authentication","scheme":"bearer"}},"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/agent-jobs":{"get":{"summary":"List Agent Jobs","operationId":"list_agent_jobs_agent_jobs_get","parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response List Agent Jobs Agent Jobs Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## POST /agent-jobs > Create Agent Job ```json {"openapi":"3.1.0","info":{"title":"Codeset API","version":"1.0.0"},"servers":[{"url":"/api/v1"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","description":"Bearer token for API authentication","scheme":"bearer"}},"schemas":{"AgentJobRequest":{"properties":{"repo":{"type":"string","title":"Repo","description":"Repository identifier as owner/repo."},"ref":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ref","description":"Optional ref or branch."},"agent_id":{"type":"string","title":"Agent Id","description":"Agent type (e.g. cursor)."}},"type":"object","required":["repo","agent_id"],"title":"AgentJobRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/agent-jobs":{"post":{"summary":"Create Agent Job","operationId":"create_agent_job_agent_jobs_post","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentJobRequest"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Create Agent Job Agent Jobs Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## GET /agent-jobs/{job\_id} > Get Agent Job ```json {"openapi":"3.1.0","info":{"title":"Codeset API","version":"1.0.0"},"servers":[{"url":"/api/v1"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","description":"Bearer token for API authentication","scheme":"bearer"}},"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/agent-jobs/{job_id}":{"get":{"summary":"Get Agent Job","operationId":"get_agent_job_agent_jobs__job_id__get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Get Agent Job Agent Jobs Job Id Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` ## POST /agent-jobs/{job\_id}/completion > Agent Job Completion ```json {"openapi":"3.1.0","info":{"title":"Codeset API","version":"1.0.0"},"servers":[{"url":"/api/v1"}],"paths":{"/agent-jobs/{job_id}/completion":{"post":{"summary":"Agent Job Completion","operationId":"agent_job_completion_agent_jobs__job_id__completion_post","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentJobCompletionRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"title":"Response Agent Job Completion Agent Jobs Job Id Completion Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"AgentJobCompletionRequest":{"properties":{"secret":{"type":"string","title":"Secret","description":"Must match the job's completion_secret."},"outcome":{"type":"string","enum":["completed","error"],"title":"Outcome"},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message","description":"When outcome is error, stored on the job."}},"type":"object","required":["secret","outcome"],"title":"AgentJobCompletionRequest"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}} ``` ## GET /agent-jobs/{job\_id}/result > Get Agent Job Result ```json {"openapi":"3.1.0","info":{"title":"Codeset API","version":"1.0.0"},"servers":[{"url":"/api/v1"}],"security":[{"HTTPBearer":[]}],"components":{"securitySchemes":{"HTTPBearer":{"type":"http","description":"Bearer token for API authentication","scheme":"bearer"}},"schemas":{"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/agent-jobs/{job_id}/result":{"get":{"summary":"Get Agent Job Result","operationId":"get_agent_job_result_agent_jobs__job_id__result_get","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}},{"name":"agent_id","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"null"}],"title":"Agent Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}} ``` --- # Agent Instructions: Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter: ``` GET https://codeset.gitbook.io/codeset-documentation/api-reference/codeset-api.md?ask= ``` The question should be specific, self-contained, and written in natural language. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.