AgentsCode API Reference

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

curl --request GET \
  --url https://api.agentscode.dev/v1/agents \
  --header 'Authorization: Bearer <token_here>' \
  --header 'content-type: application/json'

[
  {
    "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/:agentId

curl --request POST \
  --url https://api.agentscode.dev/v1/agents/event-scheduler \
  --header 'Authorization: Bearer <token_here>' \
  --header 'content-type: application/json' \
  --data '{
  "input": "Book a appointment for tomorrow with Jeff at 10am"
}'

Parameters

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/:agentJobId

curl --request GET \
  --url https://api.agentscode.dev/v1/agents/event-scheduler/<agent_job_id> \
  --header 'Authorization: Bearer <token_here>' \
  --header 'content-type: application/json'

Agent 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

curl --request GET \
  --url https://api.agentscode.dev/v1/credits/balance \
  --header 'Authorization: Bearer <token_here>' \
  --header 'content-type: application/json'

{
  "available": 100,
  "used": 50
}

Credit Usage History

Retrieve your credit usage history.

GET /credits/history

curl --request GET \
  --url https://api.agentscode.dev/v1/credits/history \
  --header 'Authorization: Bearer <token_here>' \
  --header 'content-type: application/json'

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