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
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

ParameterTypeDescription
inputobjectRequired. Input parameters specific to the agent type
contextDatastringOptional. 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:

StatusDescription
queuedThe agent run has been accepted and is waiting to be processed
activeThe agent is currently executing
completedThe agent has successfully completed its task
failedThe agent encountered an error and could not complete the task
cancelledThe 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.

CodeDescription
200Success
400Bad Request - Invalid parameters
401Unauthorized - Invalid API key
404Not Found - Resource not found
429Too Many Requests - Rate limit exceeded
500Server 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

FieldTypeDescription
runsarrayArray of run objects with credit usage details
runs[].idstringUnique identifier for the run
runs[].agentstringThe type of agent used for this run
runs[].creditsUsednumberNumber of credits consumed by this run
runs[].startedAtstringISO timestamp when the run was initiated
runs[].completedAtstringISO timestamp when the run completed
runs[].durationnumberDuration of the run in seconds
runs[].jobIdstringThe job identifier for this run
runs[].statusstringCurrent status of the run (see Agent Status Values)
hasMorebooleanIndicates if there are more results available
nextCursorstringPagination 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 1 month ago