## 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: ```bash Authorization: Bearer ``` ## Base URL All API requests should be made to: https://api.agentscode.dev/v1 ## Call an Agent ### The Agent Object ```json { "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. ```http GET /agents ``` ' \\ --header 'content-type: application/json' ` }, { name: "JavaScript", language: "javascript", code: ` const url = 'https://api.agentscode.dev/v1/agents'; const options = { method: 'GET', headers: {'content-type': 'application/json', Authorization: 'Bearer '}, }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ` }, { name: "Python", language: "python", code: ` import requests url = "https://api.agentscode.dev/v1/agents" headers = { "content-type": "application/json", "Authorization": "Bearer " } response = requests.get(url, headers=headers) print(response.json()) ` }, { name: "n8n", language: "n8n", code: { "nodes": [ { "parameters": {}, "type": "n8n-nodes-base.manualTrigger", "typeVersion": 1, "position": [ 0, 0 ], "id": "56a58367-1c8f-49e7-9f67-6ba778e903ee", "name": "When clicking 'Test workflow'" }, { "parameters": { "url": "https://api.agentscode.dev/v1/agents", "sendHeaders": true, "headerParameters": { "parameters": [ { "name": "Authorization", "value": "Bearer " } ] }, "options": {} }, "type": "n8n-nodes-base.httpRequest", "typeVersion": 4.2, "position": [ 180, 0 ], "id": "93431f29-1db7-4e9d-8ef3-d9cf00c526f6", "name": "HTTP Request" } ], "connections": { "When clicking 'Test workflow'": { "main": [ [ { "node": "HTTP Request", "type": "main", "index": 0 } ] ] } }, "pinData": {}, } } ]} /> ```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. ```http POST /agents/:agentId ``` ' \\ --header 'content-type: application/json' \\ --data '{ "input": "Book a appointment for tomorrow with Jeff at 10am" }' ` }, { name: "JavaScript", language: "javascript", code: ` const url = 'https://api.agentscode.dev/v1/agents/event-scheduler'; const options = { method: 'POST', headers: {'content-type': 'application/json', Authorization: 'Bearer '}, body: '{"input":"Book a appointment for tomorrow with Jeff at 10am"}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ` }, { name: "Python", language: "python", code: ` import requests url = "https://api.agentscode.dev/v1/agents/event-scheduler" payload = { "input": "Book a appointment for tomorrow with Jeff at 10am" } headers = { "content-type": "application/json", "Authorization": "Bearer " } response = requests.post(url, json=payload, headers=headers) print(response.json()) ` }, { name: "n8n", language: "n8n", code: { "nodes": [ { "parameters": {}, "type": "n8n-nodes-base.manualTrigger", "typeVersion": 1, "position": [ 0, 0 ], "id": "56a58367-1c8f-49e7-9f67-6ba778e903ee", "name": "When clicking 'Test workflow'" }, { "parameters": { "method": "POST", "url": "https://api.agentscode.dev/v1/agents/event-scheduler", "sendHeaders": true, "headerParameters": { "parameters": [ { "name": "Authorization", "value": "Bearer " } ] }, "sendBody": true, "bodyParameters": { "parameters": [ { "name": "input", "value": "Book a appointment for tomorrow with Jeff at 10am" } ] }, "options": {} }, "type": "n8n-nodes-base.httpRequest", "typeVersion": 4.2, "position": [ 180, 0 ], "id": "93431f29-1db7-4e9d-8ef3-d9cf00c526f6", "name": "HTTP Request" } ], "connections": { "When clicking 'Test workflow'": { "main": [ [ { "node": "HTTP Request", "type": "main", "index": 0 } ] ] } }, "pinData": {}, } } ]} /> #### Parameters

Parameter	Type	Description
`input`	object	Required. Input parameters specific to the agent type
`contextData`	string	Optional. Additional context for the agent

#### Response ```json { "jobId": "ba773b85-af92-47bd-ad3h-c2r8b72n525j", "status": "queued" } ``` ## Get Agent Response Get the response of an agent run. ```http GET /agents/:agentId/:agentJobId ``` \\ --header 'Authorization: Bearer ' \\ --header 'content-type: application/json' ` }, { name: "JavaScript", language: "javascript", code: ` const url = 'https://api.agentscode.dev/v1/agents/event-scheduler/'; const options = { method: 'GET', headers: {'content-type': 'application/json', Authorization: 'Bearer '}, }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ` }, { name: "Python", language: "python", code: ` import requests url = "https://api.agentscode.dev/v1/agents/event-scheduler/" headers = { "content-type": "application/json", "Authorization": "Bearer " } response = requests.get(url, headers=headers) print(response.json()) ` }, { name: "n8n", language: "n8n", code: { "nodes": [ { "parameters": {}, "type": "n8n-nodes-base.manualTrigger", "typeVersion": 1, "position": [ 0, 0 ], "id": "56a58367-1c8f-49e7-9f67-6ba778e903ee", "name": "When clicking ‘Test workflow’" }, { "parameters": { "url": "https://api.agentscode.dev/v1/agents/event-scheduler/", "sendHeaders": true, "headerParameters": { "parameters": [ { "name": "Authorization", "value": "Bearer " } ] }, "options": {} }, "type": "n8n-nodes-base.httpRequest", "typeVersion": 4.2, "position": [ 180, 0 ], "id": "80b3df6d-e852-4589-8e15-cbb8654b8571", "name": "HTTP Request" } ], "connections": { "When clicking ‘Test workflow’": { "main": [ [ { "node": "HTTP Request", "type": "main", "index": 0 } ] ] } }, "pinData": {}, } } ]} /> ### Agent Run Object ```json { "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. ```http GET /credits/balance ``` ' \\ --header 'content-type: application/json' ` }, { name: "JavaScript", language: "javascript", code: ` const url = 'https://api.agentscode.dev/v1/credits/balance'; const options = { method: 'GET', headers: {'content-type': 'application/json', Authorization: 'Bearer '}, }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ` }, { name: "Python", language: "python", code: ` import requests url = "https://api.agentscode.dev/v1/credits/balance" headers = { "content-type": "application/json", "Authorization": "Bearer " } response = requests.get(url, headers=headers) print(response.json()) ` }, { name: "n8n", language: "n8n", code: { "nodes": [ { "parameters": {}, "type": "n8n-nodes-base.manualTrigger", "typeVersion": 1, "position": [ 0, 0 ], "id": "56a58367-1c8f-49e7-9f67-6ba778e903ee", "name": "When clicking 'Test workflow'" }, { "parameters": { "url": "https://api.agentscode.dev/v1/credits/balance", "sendHeaders": true, "headerParameters": { "parameters": [ { "name": "Authorization", "value": "Bearer " } ] }, "sendBody": true, "bodyParameters": { "parameters": [ {} ] }, "options": {} }, "type": "n8n-nodes-base.httpRequest", "typeVersion": 4.2, "position": [ 180, 0 ], "id": "80b3df6d-e852-4589-8e15-cbb8654b8571", "name": "HTTP Request" } ], "connections": { "When clicking 'Test workflow'": { "main": [ [ { "node": "HTTP Request", "type": "main", "index": 0 } ] ] } }, "pinData": {}, } } ]} /> ```json { "available": 100, "used": 50 } ``` ### Credit Usage History Retrieve your credit usage history. ```http GET /credits/history ``` ' \\ --header 'content-type: application/json' ` }, { name: "JavaScript", language: "javascript", code: ` const url = 'https://api.agentscode.dev/v1/credits/history'; const options = { method: 'GET', headers: {'content-type': 'application/json', Authorization: 'Bearer '}, }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } `}, { name: "Python", language: "python", code: ` import requests url = "https://api.agentscode.dev/v1/credits/history" headers = { "content-type": "application/json", "Authorization": "Bearer " } response = requests.get(url, headers=headers) print(response.json()) ` }, { name: "n8n", language: "n8n", code: { "nodes": [ { "parameters": {}, "type": "n8n-nodes-base.manualTrigger", "typeVersion": 1, "position": [ 0, 0 ], "id": "56a58367-1c8f-49e7-9f67-6ba778e903ee", "name": "When clicking 'Test workflow'" }, { "parameters": { "url": "https://api.agentscode.dev/v1/credits/history", "sendHeaders": true, "headerParameters": { "parameters": [ { "name": "Authorization", "value": "Bearer " } ] }, "sendBody": true, "bodyParameters": { "parameters": [ {} ] }, "options": {} }, "type": "n8n-nodes-base.httpRequest", "typeVersion": 4.2, "position": [ 180, 0 ], "id": "80b3df6d-e852-4589-8e15-cbb8654b8571", "name": "HTTP Request" } ], "connections": { "When clicking 'Test workflow'": { "main": [ [ { "node": "HTTP Request", "type": "main", "index": 0 } ] ] } }, "pinData": {}, } } ]} /> #### 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 ```json { "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" } ```

Create an Account

Get Your API Key

Install the SDK

Need Help?