API Overview

The Deeployd API provides programmatic access to all platform features. Build custom integrations, automate workflows, and embed AI agents in your applications.

Base URL

https://api.deeployd.com/v1

Authentication

All API requests require authentication via API key:

curl https://api.deeployd.com/v1/agents \
  -H "Authorization: Bearer YOUR_API_KEY"

See API Authentication for details on creating and managing API keys.

Request Format

Content Type

All requests should use JSON:

curl https://api.deeployd.com/v1/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "My Agent", "systemPrompt": "..."}'

Query Parameters

For GET requests, use query parameters:

GET /v1/agents?limit=10&offset=0&teamId=team-123

Response Format

Success Response

{
  "data": {
    "id": "agent-123",
    "name": "My Agent",
    "createdAt": "2024-01-15T10:00:00Z"
  }
}

List Response

{
  "data": [
    { "id": "agent-1", "name": "Agent 1" },
    { "id": "agent-2", "name": "Agent 2" }
  ],
  "pagination": {
    "total": 50,
    "limit": 10,
    "offset": 0,
    "hasMore": true
  }
}

Error Response

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Name is required",
    "details": {
      "field": "name",
      "reason": "required"
    }
  }
}

HTTP Status Codes

Code	Meaning
200	Success
201	Created
204	No Content (successful delete)
400	Bad Request - Invalid parameters
401	Unauthorized - Invalid or missing API key
403	Forbidden - Insufficient permissions
404	Not Found
409	Conflict - Resource already exists
422	Unprocessable Entity - Validation error
429	Rate Limited
500	Internal Server Error

Error Codes

Code	Description
AUTHENTICATION_ERROR	Invalid API key
AUTHORIZATION_ERROR	Missing permissions
VALIDATION_ERROR	Invalid request parameters
NOT_FOUND	Resource doesn't exist
CONFLICT	Resource conflict
RATE_LIMITED	Too many requests
INTERNAL_ERROR	Server error

Rate Limits

Plan	Requests/min	Burst
Starter	60	100
Pro	300	500
Business	1000	2000
Enterprise	Custom	Custom

Rate limit headers included in responses:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 299
X-RateLimit-Reset: 1705312200

Pagination

List endpoints support pagination:

GET /v1/agents?limit=20&offset=40

Parameter	Type	Default	Max
limit	integer	20	100
offset	integer	0	-

Response includes pagination info:

{
  "pagination": {
    "total": 150,
    "limit": 20,
    "offset": 40,
    "hasMore": true
  }
}

Filtering

Many endpoints support filtering:

GET /v1/agents?teamId=team-123&state=active
GET /v1/conversations?userId=user-456&startDate=2024-01-01

Sorting

Use sort parameter:

GET /v1/agents?sort=createdAt:desc
GET /v1/conversations?sort=updatedAt:asc

Versioning

The API uses date-based versioning:

curl https://api.deeployd.com/v1/agents \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Deeployd-Version: 2024-12-01"

Without a version header, requests use the latest version. Pin to a specific version for stability.

SDKs

Official SDKs available:

TypeScript/JavaScript

npm install @deeployd/sdk

import { DeepLoyd } from '@deeployd/sdk';

const client = new DeepLoyd({ apiKey: 'YOUR_API_KEY' });

const agent = await client.agents.create({
  name: 'My Agent',
  systemPrompt: 'You are a helpful assistant...'
});

Python

pip install deeployd

from deeployd import DeepLoyd

client = DeepLoyd(api_key="YOUR_API_KEY")

agent = client.agents.create(
    name="My Agent",
    system_prompt="You are a helpful assistant..."
)

API Endpoints

Agents

Method	Endpoint	Description
GET	/agents	List agents
POST	/agents	Create agent
GET	/agents/:id	Get agent
PUT	/agents/:id	Update agent
DELETE	/agents/:id	Delete agent
POST	/agents/:id/chat	Chat with agent

Conversations

Method	Endpoint	Description
GET	/conversations	List conversations
GET	/conversations/:id	Get conversation
DELETE	/conversations/:id	Delete conversation
POST	/conversations/:id/end	End conversation

Tasks

Method	Endpoint	Description
GET	/tasks	List tasks
POST	/tasks	Create task
GET	/tasks/:id	Get task
POST	/tasks/:id/run	Run task
DELETE	/tasks/:id	Cancel task

Workflows

Method	Endpoint	Description
GET	/workflows	List workflows
POST	/workflows	Create workflow
GET	/workflows/:id	Get workflow
PUT	/workflows/:id	Update workflow
DELETE	/workflows/:id	Delete workflow
POST	/workflows/:id/run	Run workflow

Memory

Method	Endpoint	Description
GET	/memory	Get memory value
PUT	/memory	Set memory value
DELETE	/memory	Delete memory
POST	/memory/search	Search memories

Templates

Method	Endpoint	Description
GET	/templates	List templates
POST	/templates	Create template
GET	/templates/:id	Get template
PUT	/templates/:id	Update template
DELETE	/templates/:id	Delete template

Webhooks

Receive real-time events via webhooks:

POST /v1/webhooks
{
  "url": "https://your-app.com/webhooks",
  "events": ["conversation.completed", "task.failed"]
}

See Webhooks for details.

Testing

Use test mode for development:

const client = new DeepLoyd({
  apiKey: 'sk_test_...',  // Test key
  testMode: true
});

Test mode:

• Uses sandbox environment
• No charges incurred
• Data not persisted
• Rate limits relaxed

Support

• Documentation: You're here!
• API Status: status.deeployd.com
• Discord: discord.gg/deeployd
• Email: api-support@deeployd.com

---

Next: Learn about API Authentication to secure your API requests.