DocumentationAgentsCode API Reference
AgentsCode API Reference
Welcome to the AgentsCode API. If you have any questions, please don't hesitate to reach out.
Updated 4 days ago
Welcome to the AgentsCode API. If you have any questions, please don't hesitate to reach out.
The AgentsCode API uses API keys to authenticate requests. You can manage your API keys from your Dashboard.
Authentication is done via an Authorization header:
Authorization: Bearer <API_KEY_HERE>All API requests should be made to: https://api.agentscode.dev/v1
{
"id": "agent_123456",
"name": "youtube-transcription",
"displayName": "YouTube Transcription",
"version": "1.0.0",
"credits": 5,
"description": "Transcribe YouTube videos to text",
"status": "ACTIVE",
"runCount": 42
}Retrieve all available agents for your account.
GET /agents[
{
"id": "agent-name",
"name": "Agent Name",
"description": "Description of what the agent does",
"version": "1.0.0",
"credits": 5,
"status": "ACTIVE"
}
]Returns an array of agent objects.
Run an agent with specific input parameters.
POST /agents/:agentId| Parameter | Type | Description |
|---|---|---|
input | object | Required. Input parameters specific to the agent type |
contextData | string | Optional. Additional context for the agent |
{
"jobId": "ba773b85-af92-47bd-ad3h-c2r8b72n525j",
"status": "queued"
}Get the response of an agent run.
GET /agents/:agentId/:agentJobId{
"jobId": "ba773b85-af92-47bd-ad3h-c2r8b72n525j",
"status": "completed",
"progress": 100,
"result": {...}
}Agents can have one of the following status values:
| Status | Description |
|---|---|
queued | The agent run has been accepted and is waiting to be processed |
active | The agent is currently executing |
completed | The agent has successfully completed its task |
failed | The agent encountered an error and could not complete the task |
cancelled | The agent run was cancelled by the user or the system |
The AgentsCode API uses HTTP response codes to indicate the success or failure of an API request.
| Code | Description |
|---|---|
| 200 | Success |
| 400 | Bad Request - Invalid parameters |
| 401 | Unauthorized - Invalid API key |
| 404 | Not Found - Resource not found |
| 429 | Too Many Requests - Rate limit exceeded |
| 500 | Server Error - Something went wrong on our end |
Credits are consumed when running agents and when agents are ran successfully. You're only charged for successful runs. Different agents require different amounts of credits.
Retrieve your current credit balance.
GET /credits/balance{
"available": 100,
"used": 50
}Retrieve your credit usage history.
GET /credits/history| Field | Type | Description |
|---|---|---|
runs | array | Array of run objects with credit usage details |
runs[].id | string | Unique identifier for the run |
runs[].agent | string | The type of agent used for this run |
runs[].creditsUsed | number | Number of credits consumed by this run |
runs[].startedAt | string | ISO timestamp when the run was initiated |
runs[].completedAt | string | ISO timestamp when the run completed |
runs[].duration | number | Duration of the run in seconds |
runs[].jobId | string | The job identifier for this run |
runs[].status | string | Current status of the run (see Agent Status Values) |
hasMore | boolean | Indicates if there are more results available |
nextCursor | string | Pagination cursor to use for fetching the next page of results |
{
"runs": [
{
"id": "cm9fd21dc000ovp62yilaf9kw",
"agent": "youtube-transcript",
"creditsUsed": 20,
"startedAt": "2025-04-13T00:42:59.953Z",
"completedAt": "2025-04-13T00:43:12.095Z",
"duration": 10.142,
"jobId": "a9c5f4e1-de05-4166-5aa4-6f97c518fa5c",
"status": "completed"
}
],
"hasMore": true,
"nextCursor": "cm9wt68c0i01brbmvg5t1d3a"
}