#divisions API Reference

📖 Introduction

The #divisions API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Base URL: https://api.divisions.dev/v1

🔐 Authentication

Authenticate your API requests using Bearer tokens in the Authorization header. Generate tokens from your dashboard settings.

HTTP Header

Authorization: Bearer dv_live_sk_8f7d6e5c4b3a2f1e0d9c8b7a6f5e4d3c

Never expose your secret keys in client-side code. Use public keys for frontend requests where applicable.

👥 List Users

GET /users Returns a paginated list of all users

Query Parameters

Name	Type	Required	Description
page	integer	Optional	Page number for pagination (default: 1)
limit	integer	Optional	Number of results per page (default: 20, max: 100)
role	string	Optional	Filter by user role: admin, member, viewer

Response Example

JSON

{
  "data": [
    {
      "id": "usr_29847561",
      "name": "Sarah Kim",
      "email": "sarah@novatech.dev",
      "role": "admin",
      "created_at": "2024-08-15T14:23:11Z"
    }
  ],
  "meta": {
    "total": 42,
    "page": 1,
    "limit": 20
  }
}

➕ Create User

POST /users Creates a new user account

Request Body

Name	Type	Required	Description
name	string	Required	Full name of the user
email	string	Required	Valid email address
role	string	Optional	User role. Defaults to `member`

Request Example

cURL

curl -X POST https://api.divisions.dev/v1/users \\
  -H "Authorization: Bearer dv_live_sk_..." \\
  -H "Content-Type: application/json" \\
  -d '{
    "name": "Marcus Rivera",
    "email": "marcus@dataflow.io",
    "role": "viewer"
  }'

📁 Projects

GET /projects List all projects with optional filters

Response Codes

200 Success - Returns array of projects

401 Unauthorized - Invalid token

429 Rate limited - Too many requests

🔔 Webhooks

Webhooks allow you to receive real-time notifications when events occur in your #divisions account. Configure endpoints in your dashboard.

POST /webhooks Register a new webhook endpoint

Webhook Signature Verification

Always verify webhook signatures using the X-Divisions-Signature header and your webhook secret.

JavaScript

const crypto = require('crypto');

function verifyWebhook(payload, signature, secret) {
  const hmac = crypto.createHmac('sha256', secret);
  const digest = hmac.update(payload).digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(digest)
  );
}

⚠️ Error Handling

The #divisions API uses conventional HTTP response codes to indicate success or failure of requests. Codes in the 2xx range indicate success, 4xx indicate client errors, and 5xx indicate server errors.

Code	Meaning	Description
400	Bad Request	Missing or invalid parameters
401	Unauthorized	Invalid or expired API key
403	Forbidden	Insufficient permissions
404	Not Found	Resource does not exist
429	Too Many Requests	Rate limit exceeded
500	Server Error	Internal system failure