API Reference

February 25, 2025 32174b4 Edit this page

API Reference 🗄️ Archived

Complete API endpoint reference documentation

API Reference

Complete reference for all API endpoints.

Base URL

https://api.example.com/v1

Resources

List Resources

GET /resources

Parameters:

Parameter	Type	Description
`page`	integer	Page number (default: 1)
`per_page`	integer	Items per page (default: 20, max: 100)
`sort`	string	Sort field (prefix with - for descending)
`filter[status]`	string	Filter by status
`filter[type]`	string	Filter by type

Example Request:

curl "https://api.example.com/v1/resources?page=1&per_page=50&sort=-created_at" \
  -H "Authorization: Bearer YOUR_TOKEN"

Example Response:

{
  "data": [
    {
      "id": "res_123",
      "name": "Example Resource",
      "type": "standard",
      "status": "active",
      "created_at": "2025-01-15T10:00:00Z",
      "updated_at": "2025-01-15T10:00:00Z"
    }
  ],
  "meta": {
    "page": 1,
    "per_page": 50,
    "total": 150,
    "total_pages": 3
  }
}

Get Resource

GET /resources/{id}

Example Request:

curl https://api.example.com/v1/resources/res_123 \
  -H "Authorization: Bearer YOUR_TOKEN"

Example Response:

{
  "data": {
    "id": "res_123",
    "name": "Example Resource",
    "description": "A sample resource",
    "type": "standard",
    "status": "active",
    "metadata": {
      "custom_field": "value"
    },
    "created_at": "2025-01-15T10:00:00Z",
    "updated_at": "2025-01-15T10:00:00Z"
  }
}

Create Resource

POST /resources

Request Body:

{
  "name": "New Resource",
  "description": "Resource description",
  "type": "standard",
  "metadata": {
    "key": "value"
  }
}

Example Request:

curl -X POST https://api.example.com/v1/resources \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "New Resource",
    "type": "standard"
  }'

Example Response:

{
  "data": {
    "id": "res_456",
    "name": "New Resource",
    "type": "standard",
    "status": "active",
    "created_at": "2025-02-25T10:00:00Z",
    "updated_at": "2025-02-25T10:00:00Z"
  }
}

Update Resource

PATCH /resources/{id}

Request Body:

{
  "name": "Updated Name",
  "description": "Updated description"
}

Example Request:

curl -X PATCH https://api.example.com/v1/resources/res_123 \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Updated Name"
  }'

Delete Resource

DELETE /resources/{id}

Example Request:

curl -X DELETE https://api.example.com/v1/resources/res_123 \
  -H "Authorization: Bearer YOUR_TOKEN"

Response: 204 No Content

Users

Get Current User

GET /users/me

Example Response:

{
  "data": {
    "id": "usr_789",
    "email": "user@example.com",
    "username": "johndoe",
    "profile": {
      "first_name": "John",
      "last_name": "Doe",
      "avatar_url": "https://example.com/avatar.jpg"
    },
    "created_at": "2024-06-01T10:00:00Z"
  }
}

Update User Profile

PATCH /users/me

Request Body:

{
  "profile": {
    "first_name": "Jane",
    "last_name": "Smith"
  }
}

List Users

GET /users

Parameters:

Parameter	Type	Description
`page`	integer	Page number
`per_page`	integer	Items per page
`search`	string	Search query
`role`	string	Filter by role

Organizations

List Organizations

GET /organizations

Get Organization

GET /organizations/{id}

Create Organization

POST /organizations

Request Body:

{
  "name": "My Organization",
  "slug": "my-org"
}

Update Organization

PATCH /organizations/{id}

Delete Organization

DELETE /organizations/{id}

List Organization Members

GET /organizations/{id}/members

Add Organization Member

POST /organizations/{id}/members

Request Body:

{
  "user_id": "usr_789",
  "role": "member"
}

Remove Organization Member

DELETE /organizations/{id}/members/{user_id}

Authentication

Login

POST /auth/login

Request Body:

{
  "email": "user@example.com",
  "password": "password"
}

Response:

{
  "access_token": "eyJhbGc...",
  "refresh_token": "eyJhbGc...",
  "token_type": "Bearer",
  "expires_in": 3600
}

Refresh Token

POST /auth/refresh

Request Body:

{
  "refresh_token": "eyJhbGc..."
}

Logout

POST /auth/logout

Register

POST /auth/register

Request Body:

{
  "email": "newuser@example.com",
  "username": "newuser",
  "password": "securepassword"
}

Webhooks

List Webhooks

GET /webhooks

Create Webhook

POST /webhooks

Request Body:

{
  "url": "https://your-app.com/webhook",
  "events": ["resource.created", "resource.updated"],
  "secret": "your_secret"
}

Update Webhook

PATCH /webhooks/{id}

Delete Webhook

DELETE /webhooks/{id}

Test Webhook

POST /webhooks/{id}/test

Rate Limits

All endpoints are subject to rate limiting:

Plan	Requests per minute
Free	60
Pro	600
Enterprise	6000

Rate limit headers:

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 599
X-RateLimit-Reset: 1609459200

Error Codes

Code	HTTP Status	Description
`invalid_request`	400	Request validation failed
`authentication_required`	401	Missing authentication
`insufficient_permissions`	403	Insufficient permissions
`resource_not_found`	404	Resource not found
`rate_limit_exceeded`	429	Rate limit exceeded
`internal_server_error`	500	Internal server error

Pagination

All list endpoints support pagination:

GET /resources?page=2&per_page=50

Response includes pagination metadata:

{
  "data": [...],
  "meta": {
    "page": 2,
    "per_page": 50,
    "total": 500,
    "total_pages": 10
  }
}

Authentication Methods SDKs and Libraries