API Endpoints

Complete reference for all available API endpoints in C15T Backend, including request/response formats, error handling, and rate limiting.

This document provides a comprehensive reference for all available API endpoints in the C15T Backend package.

Base URL

All endpoints are prefixed with /api/c15t/ by default. This can be customized using the basePath option when creating a C15T instance.

Authentication

Most endpoints require authentication. Include the authentication token in the Authorization header:

Authorization: Bearer your-token-here

Endpoints

Status

Get the current status of the C15T instance.

GET /api/c15t/status

Response

{
  "status": "ok",
  "version": "1.0.0",
  "timestamp": "2024-03-20T12:00:00Z",
  "storage": {
    "type": "memory",
    "available": true
  }
}

Create a new consent record.

POST /api/c15t/consent
Content-Type: application/json
 
{
  "userId": "user123",
  "purpose": "marketing",
  "scope": ["email", "analytics"],
  "expiresAt": "2024-12-31T23:59:59Z"
}

Response

{
  "id": "consent123",
  "userId": "user123",
  "purpose": "marketing",
  "scope": ["email", "analytics"],
  "status": "active",
  "createdAt": "2024-03-20T12:00:00Z",
  "expiresAt": "2024-12-31T23:59:59Z"
}

Retrieve a specific consent record.

GET /api/c15t/consent/{id}

Response

{
  "id": "consent123",
  "userId": "user123",
  "purpose": "marketing",
  "scope": ["email", "analytics"],
  "status": "active",
  "createdAt": "2024-03-20T12:00:00Z",
  "expiresAt": "2024-12-31T23:59:59Z"
}

Update an existing consent record.

PUT /api/c15t/consent/{id}
Content-Type: application/json
 
{
  "status": "revoked",
  "revokedAt": "2024-03-20T12:00:00Z"
}

Response

{
  "id": "consent123",
  "userId": "user123",
  "purpose": "marketing",
  "scope": ["email", "analytics"],
  "status": "revoked",
  "createdAt": "2024-03-20T12:00:00Z",
  "expiresAt": "2024-12-31T23:59:59Z",
  "revokedAt": "2024-03-20T12:00:00Z"
}

List Consents

Retrieve a list of consent records with optional filtering.

GET /api/c15t/consents

Query Parameters

userId: Filter by user ID
purpose: Filter by purpose
status: Filter by status
page: Page number (default: 1)
limit: Items per page (default: 20)

Response

{
  "items": [
    {
      "id": "consent123",
      "userId": "user123",
      "purpose": "marketing",
      "scope": ["email", "analytics"],
      "status": "active",
      "createdAt": "2024-03-20T12:00:00Z",
      "expiresAt": "2024-12-31T23:59:59Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}

User Management

Create User

Create a new user.

POST /api/c15t/users
Content-Type: application/json
 
{
  "email": "user@example.com",
  "name": "John Doe",
  "metadata": {
    "company": "Example Corp",
    "role": "customer"
  }
}

Response

{
  "id": "user123",
  "email": "user@example.com",
  "name": "John Doe",
  "metadata": {
    "company": "Example Corp",
    "role": "customer"
  },
  "createdAt": "2024-03-20T12:00:00Z"
}

Get User

Retrieve a specific user.

GET /api/c15t/users/{id}

Response

{
  "id": "user123",
  "email": "user@example.com",
  "name": "John Doe",
  "metadata": {
    "company": "Example Corp",
    "role": "customer"
  },
  "createdAt": "2024-03-20T12:00:00Z"
}

Update User

Update an existing user.

PUT /api/c15t/users/{id}
Content-Type: application/json
 
{
  "name": "John Smith",
  "metadata": {
    "company": "New Corp",
    "role": "admin"
  }
}

Response

{
  "id": "user123",
  "email": "user@example.com",
  "name": "John Smith",
  "metadata": {
    "company": "New Corp",
    "role": "admin"
  },
  "createdAt": "2024-03-20T12:00:00Z",
  "updatedAt": "2024-03-20T12:30:00Z"
}

List Users

Retrieve a list of users with optional filtering.

GET /api/c15t/users

Query Parameters

email: Filter by email
role: Filter by role
page: Page number (default: 1)
limit: Items per page (default: 20)

Response

{
  "items": [
    {
      "id": "user123",
      "email": "user@example.com",
      "name": "John Doe",
      "metadata": {
        "company": "Example Corp",
        "role": "customer"
      },
      "createdAt": "2024-03-20T12:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}

Audit Logs

Get Audit Logs

Retrieve audit logs with optional filtering.

GET /api/c15t/audit-logs

Query Parameters

userId: Filter by user ID
action: Filter by action type
resource: Filter by resource type
startDate: Filter by start date
endDate: Filter by end date
page: Page number (default: 1)
limit: Items per page (default: 20)

Response

{
  "items": [
    {
      "id": "log123",
      "userId": "user123",
      "action": "consent.created",
      "resource": "consent",
      "resourceId": "consent123",
      "metadata": {
        "purpose": "marketing",
        "scope": ["email"]
      },
      "timestamp": "2024-03-20T12:00:00Z"
    }
  ],
  "total": 1,
  "page": 1,
  "limit": 20
}

Error Responses

All endpoints may return the following error responses:

400 Bad Request

{
  "error": "Bad Request",
  "message": "Invalid input data",
  "details": {
    "field": "email",
    "message": "Invalid email format"
  }
}

401 Unauthorized

{
  "error": "Unauthorized",
  "message": "Authentication required"
}

403 Forbidden

{
  "error": "Forbidden",
  "message": "Insufficient permissions"
}

404 Not Found

{
  "error": "Not Found",
  "message": "Resource not found"
}

500 Internal Server Error

{
  "error": "Internal Server Error",
  "message": "An unexpected error occurred"
}

Rate Limiting

API requests are rate-limited by default. The following headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 99
X-RateLimit-Reset: 1616234400

Pagination

List endpoints support pagination using the following query parameters:

page: Page number (default: 1)
limit: Items per page (default: 20)

Response includes pagination metadata:

{
  "items": [...],
  "total": 100,
  "page": 1,
  "limit": 20,
  "totalPages": 5
}

Filtering

List endpoints support filtering using query parameters:

GET /api/c15t/consents?userId=user123&status=active&purpose=marketing

Sorting

List endpoints support sorting using the sort query parameter:

GET /api/c15t/consents?sort=createdAt:desc

Field Selection

Use the fields query parameter to select specific fields:

GET /api/c15t/consents?fields=id,userId,status

API Endpoints

On this page