API Documentation

Welcome to the #divisions API reference. Our RESTful API allows you to programmatically manage users, projects, analytics, and webhooks. All requests and responses use JSON encoding over HTTPS.

💡 Tip

Use our official SDKs for faster integration, or interact directly with the raw endpoints documented below.

Base URL & Versioning

All API requests must be made to the following base URL. We use URL path versioning to maintain backward compatibility.

Base URL

https://api.divisions.io/v1

Authentication

The API uses Bearer token authentication. Include your API key in the Authorization header of every request.

Headers

Authorization: Bearer div_live_sk_8f9a2b3c4d5e6f7g8h9i0j
Content-Type: application/json

⚠️ Security Notice

Never expose your secret API keys in client-side code. Use environment variables and server-side proxies.

Users

Manage team members, roles, and account permissions.

GET /v1/users

Returns a paginated list of all users in your organization.

Query Parameters

Parameter	Type	Description
`limit`	integer	Number of results per page (1-100). Default: 20
`cursor`	string	Pagination cursor from previous response
`role`	string	Filter by role: `admin`, `member`, `viewer`

Response

200 OK

{
  "data": [
    {
      "id": "usr_9f8e7d6c5b4a",
      "name": "Alex Morgan",
      "email": "alex@divisions.io",
      "role": "admin",
      "created_at": "2024-11-15T08:30:00Z"
    }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6MTAyMn0=",
    "has_more": true
  }
}

Projects

Create, update, and manage your division projects.

POST /v1/projects

Creates a new project workspace.

Request Body

Field	Type	Required	Description
`name`	string	Required	Project name (3-50 chars)
`description`	string		Optional project description
`region`	string		Deployment region: `us-east`, `eu-west`, `ap-south`

Example Request

JSON

{
  "name": "Q4 Marketing Campaign",
  "description": "Cross-channel analytics tracking",
  "region": "us-east"
}

PUT /v1/projects/:id

Updates an existing project configuration.

Analytics

GET /v1/analytics/summary

Returns aggregated metrics for the specified time range.

Query Parameters

Parameter	Type	Description
`start_date`	string	ISO 8601 timestamp
`end_date`	string	ISO 8601 timestamp
`granularity`	string	`hourly`, `daily`, `weekly`

Error Codes

#divisions uses conventional HTTP status codes. Error responses include a structured JSON payload.

Code	Meaning	Description
`400`	Bad Request	Invalid parameters or malformed JSON
`401`	Unauthorized	Missing or invalid API key
`403`	Forbidden	Insufficient permissions for this resource
`404`	Not Found	Resource does not exist
`429`	Too Many Requests	Rate limit exceeded. Retry after header applies.
`500`	Internal Error	Something went wrong on our end. Contact support.

Error Response Format

{
  "error": {
    "code": "invalid_request",
    "message": "Missing required field: name",
    "request_id": "req_8f9a2b3c"
  }
}

Rate Limits

API requests are limited based on your plan tier. Limits are applied per API key.

Plan	Requests/min	Burst Limit
Starter	60	10
Professional	600	50
Enterprise	Custom	Custom

Rate limit headers are included in every response:

Response Headers

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 582
X-RateLimit-Reset: 1703982400