REST API Integrations

Leverage our powerful REST API to connect your applications and automate workflows. This guide provides a comprehensive overview of our API endpoints, authentication methods, and usage examples.

Authentication

All API requests must be authenticated. We use API keys for secure access. Your API key can be found in your account settings.

Include your API key in the Authorization header as a Bearer token:

Authorization: Bearer YOUR_API_KEY

Base URL

All API endpoints are relative to the following base URL:

https://api.example.com/v1

Endpoints

GET /users

Retrieves a list of all users.

Query Parameters:

limit integer Maximum number of users to return.
offset integer Number of users to skip.

Success Response (200 OK):

[
  {
    "id": "user_abc123",
    "name": "Alice Wonderland",
    "email": "alice@example.com",
    "created_at": "2023-10-27T10:00:00Z"
  },
  {
    "id": "user_def456",
    "name": "Bob The Builder",
    "email": "bob@example.com",
    "created_at": "2023-10-27T10:05:00Z"
  }
]

Request:

GET /v1/users?limit=2&offset=0 HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_API_KEY
Accept: application/json

POST /users

Creates a new user.

Request Body (JSON):

name string (required) The name of the user.
email string (required) The email address of the user. Must be unique.
password string (required) The user's password. Must be at least 8 characters long.

Success Response (201 Created):

{
  "id": "user_ghi789",
  "name": "Charlie Chaplin",
  "email": "charlie@example.com",
  "created_at": "2023-10-27T10:15:00Z"
}

Error Response (400 Bad Request):

{
  "error": "Email address is already in use."
}

Request:

POST /v1/users HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json

{
  "name": "Charlie Chaplin",
  "email": "charlie@example.com",
  "password": "securepassword123"
}

PUT /users/{userId}

Updates an existing user.

Path Parameters:

userId string (required) The unique identifier of the user to update.

Request Body (JSON):

name string The new name of the user.
email string The new email address of the user.

Success Response (200 OK):

{
  "id": "user_ghi789",
  "name": "Charles Chaplin",
  "email": "charlie.c@example.com",
  "updated_at": "2023-10-27T11:00:00Z"
}

Request:

PUT /v1/users/user_ghi789 HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json
Accept: application/json

{
  "name": "Charles Chaplin",
  "email": "charlie.c@example.com"
}

DELETE /users/{userId}

Deletes a user.

Path Parameters:

userId string (required) The unique identifier of the user to delete.

Success Response (204 No Content):

No response body is returned on successful deletion.

Request:

DELETE /v1/users/user_ghi789 HTTP/1.1
Host: api.example.com
Authorization: Bearer YOUR_API_KEY

Error Handling

Our API uses standard HTTP status codes to indicate the success or failure of a request.

2xx: Success
400 Bad Request: The request was malformed or contained invalid parameters.
401 Unauthorized: Authentication credentials were missing or invalid.
403 Forbidden: The authenticated user does not have permission to perform the requested action.
404 Not Found: The requested resource could not be found.
429 Too Many Requests: The user has exceeded the rate limit.
500 Internal Server Error: An unexpected error occurred on the server.

Error responses will typically include a JSON object with an error key providing more details.

{
  "error": "Invalid API key provided."
}

Rate Limiting

To ensure fair usage and stability, our API enforces rate limits. Exceeding these limits will result in a 429 Too Many Requests response.

Current limits:

Requests per minute: 100
Requests per hour: 5000

The RateLimit-Remaining and RateLimit-Reset headers in the response indicate your current status.