#divisions API Reference

🌐 Base URL

All API requests are sent to the following base URL:

https://api.divisions.dev/v1

We currently support v1. Breaking changes will be communicated 90 days in advance.

Authentication

🔑 API Keys

Authenticate requests by including your API key in the Authorization header:

# Include with every request
Authorization: Bearer div_live_your_api_key_here

# Test keys are prefixed with div_test_
# Live keys are prefixed with div_live_

Keep your keys secure. Never expose them in client-side code or public repositories. You can rotate keys anytime from the Dashboard.

Endpoints

GET /projects List all projects

Retrieve a paginated list of all projects associated with your account.

Query Parameters

Parameter	Type	Required	Description
limit	integer	No	Max results per page (default: 20, max: 100)
offset	integer	No	Number of items to skip
status	string	No	Filter by: active, archived, deleted

curl -X GET \
  https://api.divisions.dev/v1/projects?limit=20 \
  -H "Authorization: Bearer div_live_xxxx"

{
  "data": [
    {
      "id": "proj_8f3a2b1c",
      "name": "E-Commerce Platform",
      "status": "active",
      "created_at": "2024-11-15T08:30:00Z"
    }
  ],
  "meta": {
    "total": 42,
    "limit": 20,
    "offset": 0
  }
}

POST /projects Create a new project

Provision a new project with configurable environments and default settings.

{
  "name": "Analytics Dashboard",
  "region": "us-east-1",
  "environments": ["dev", "staging", "prod"],
  "auto_deploy": true
}

{
  "id": "proj_9d4e7f2a",
  "name": "Analytics Dashboard",
  "status": "initializing",
  "created_at": "2025-01-10T14:22:00Z",
  "api_key": "div_proj_live_a1b2c3..."
}

POST /deployments Trigger a deployment

Initiate a new deployment for a specified project and environment. Returns a deployment ID for tracking.

{
  "project_id": "proj_8f3a2b1c",
  "environment": "production",
  "source": {
    "type": "git",
    "repo": "github.com/org/repo",
    "branch": "main"
  }
}

{
  "id": "dep_m3n5p7q9",
  "status": "queued",
  "project_id": "proj_8f3a2b1c",
  "environment": "production",
  "estimated_time": "~45s",
  "webhook_url": "https://api.divisions.dev/v1/deployments/dep_m3n5p7q9/status"
}

Rate Limits

We enforce rate limits to ensure platform stability. Limits reset on a rolling window.

Free Tier

60 req/min

Standard requests. Burst up to 100. Exceeding returns 429.

Professional

1,000 req/min

Optimized for production workloads. Includes webhook retry queues.

Enterprise

Custom

Dedicated throughput, priority routing, and SLA-backed availability.

📊 Monitoring Usage

Check your current rate limit status in the response headers of every request:

X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 842
X-RateLimit-Reset: 1705334400

Error Codes

We use standard HTTP status codes and return detailed JSON error objects.

Code	Status	Description
400	Bad Request	Invalid syntax or missing required parameters
401	Unauthorized	Missing or invalid API key
403	Forbidden	Insufficient permissions for the requested resource
404	Not Found	Resource does not exist or has been deleted
429	Too Many Requests	Rate limit exceeded. Retry after X-RateLimit-Reset
500	Server Error	Internal failure. Check status page for outages

📦 Error Response Format

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or expired API key",
    "details": "Key prefix 'div_live_' expected",
    "request_id": "req_7x9m2p4q"
  }
}

SDKs & Libraries

Official client libraries for rapid integration. All SDKs support async operations, typed responses, and automatic retries.

JavaScript / TypeScript

npm install @divisions/sdk

Full type definitions. Works in Node.js, Deno, and browsers.

Python

pip install divisions-py

Asyncio native. Supports type hints and streaming.

Go

go get github.com/divisions/go-sdk

Thread-safe clients with connection pooling.

💬 Need Help?

Our developer support team is available 24/7. Join our community, check the docs, or open a ticket.

Join Discord Read Docs Contact Support

Developer API Reference