Documentation
DocumentationAgentsCode API Reference
AgentsCode API Reference
Welcome to the AgentsCode API. If you have any questions, please don't hesitate to reach out.
Authentication
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>Base URL
All API requests should be made to: https://api.agentscode.dev/v1
Call an Agent
The Agent Object
{
"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
}Available Agents
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"
}
]Response
Returns an array of agent objects.
Run an Agent
Run an agent with specific input parameters.
POST /agents/:agentIdParameters
| Parameter | Type | Description |
|---|---|---|
input | object | Required. Input parameters specific to the agent type |
contextData | string | Optional. Additional context for the agent |
Response
{
"jobId": "ba773b85-af92-47bd-ad3h-c2r8b72n525j",
"status": "queued"
}Get Agent Response
Get the response of an agent run.
GET /agents/:agentId/:agentJobIdAgent Run Object
{
"jobId": "ba773b85-af92-47bd-ad3h-c2r8b72n525j",
"status": "completed",
"progress": 100,
"result": {...}
}Agent Status Values
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 |
Errors
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
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.
Credit Balance
Retrieve your current credit balance.
GET /credits/balance{
"available": 100,
"used": 50
}Credit Usage History
Retrieve your credit usage history.
GET /credits/historyResponse Structure
| 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 |
Example Response
{
"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"
}Updated 9 months ago