REST API Documentation

Overview

The Core API is organised 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.example.com/v1

Authentication

The API uses API keys to authenticate requests. You can view and manage your API keys in the dashboard.

Authenticate your API requests by providing your secret key in the Authorization header.

Authorization: Bearer YOUR_API_KEY

Endpoints

1. Retrieve a User

Retrieves the details of an existing user. You need only supply the unique user identifier that was returned upon user creation.

Endpoint: GET /users/:id

Path Parameters

Example Request

curl https://api.example.com/v1/users/usr_123 \
  -H "Authorization: Bearer YOUR_API_KEY"

Example Response

{
  "id": "usr_123",
  "object": "user",
  "name": "Jane Bloggs",
  "email": "[email protected]",
  "created_at": 1672531199
}

2. Create a User

Creates a new user object.

Endpoint: POST /users

Body Parameters

Example Request

curl -X POST https://api.example.com/v1/users \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "[email protected]",
    "name": "Joe Bloggs"
  }'

Example Response

{
  "id": "usr_456",
  "object": "user",
  "name": "Joe Bloggs",
  "email": "[email protected]",
  "created_at": 1672531255
}

Error Codes

The API uses conventional HTTP response codes to indicate the success or failure of an API request.