API Introduction

The autoch.at CRM REST API provides programmatic access to your CRM data.

Base URL

https://your-instance.supabase.co/functions/v1/crm-api/v1

Replace your-instance with your Supabase project URL.

Authentication

All API requests require authentication using an API key.

API Key Header

Include your API key in the request header:

Authorization: Bearer YOUR_API_KEY

Getting an API Key

1. Log in to autoch.at CRM
2. Go to Settings → Integrations → API Keys
3. Click Create API Key
4. Set a name and select scopes
5. Copy the key immediately (shown only once)
6. Store securely

API Versioning

The API uses URL versioning:

• Current version: v1
• Version in URL: /v1/...
• Future versions: /v2/...

Request Format

Content Type

All requests use JSON:

Content-Type: application/json

Request Body

POST and PUT requests include JSON body:

{
  "field1": "value1",
  "field2": "value2"
}

Response Format

Success Response

{
  "data": {
    "id": "uuid",
    "field": "value"
  }
}

Error Response

{
  "error": {
    "message": "Error description",
    "code": "ERROR_CODE"
  }
}

HTTP Status Codes

• 200 OK: Success
• 201 Created: Resource created
• 400 Bad Request: Invalid request
• 401 Unauthorized: Invalid API key
• 403 Forbidden: Insufficient permissions
• 404 Not Found: Resource not found
• 429 Too Many Requests: Rate limit exceeded
• 500 Internal Server Error: Server error

Rate Limiting

API requests are rate-limited:

• Default: 100 requests per minute per API key
• Rate limit headers included in responses
• Exceeding limit returns 429 status

Rate Limit Headers

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1640995200

Scopes & Permissions

API keys have scoped permissions:

Available Scopes

• clients:read - Read clients
• clients:write - Create/update clients
• invoices:read - Read invoices
• invoices:write - Create/update invoices
• quotes:read - Read quotes
• quotes:write - Create/update quotes
• payments:read - Read payments
• payments:write - Create/update payments
• products:read - Read products/services
• products:write - Create/update products/services
• projects:read - Read projects
• projects:write - Create/update projects
• webhooks:read - Read webhooks
• webhooks:write - Create/update webhooks
• marketing:write - Marketing operations

Scope Requirements

Each endpoint requires specific scopes:

• Check endpoint documentation for required scopes
• Requests without required scope return 403

Idempotency

POST requests support idempotency:

Idempotency-Key: unique-key-here

• Prevents duplicate processing
• Use unique keys per request
• Same key returns same result

Tenant Context

All API requests are scoped to your tenant:

• API key is tenant-specific
• Data is automatically filtered
• Cannot access other tenants' data

Endpoints

Clients

• GET /v1/clients - List clients
• GET /v1/clients/:id - Get client
• POST /v1/clients - Create client
• PUT /v1/clients/:id - Update client
• DELETE /v1/clients/:id - Delete client

Invoices

• GET /v1/invoices - List invoices
• GET /v1/invoices/:id - Get invoice
• POST /v1/invoices - Create invoice
• PUT /v1/invoices/:id - Update invoice
• PATCH /v1/invoices/:id/status - Update status

Products & Services

• GET /v1/products - List products/services
• GET /v1/products/:id - Get product/service
• POST /v1/products - Create product/service
• PUT /v1/products/:id - Update product/service

Webhooks

• GET /v1/webhooks - List webhooks
• GET /v1/webhooks/:id - Get webhook
• POST /v1/webhooks - Create webhook
• PUT /v1/webhooks/:id - Update webhook
• DELETE /v1/webhooks/:id - Delete webhook
• POST /v1/webhooks/:id/test - Test webhook

Examples

List Clients

curl -X GET \
  'https://your-instance.supabase.co/functions/v1/crm-api/v1/clients' \
  -H 'Authorization: Bearer YOUR_API_KEY'

List Products

curl -X GET \
  'https://your-instance.supabase.co/functions/v1/crm-api/v1/products?type=service' \
  -H 'Authorization: Bearer YOUR_API_KEY'

Create Invoice

curl -X POST \
  'https://your-instance.supabase.co/functions/v1/crm-api/v1/invoices' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "client_id": "uuid",
    "due_date": "2024-12-31",
    "line_items": [
      {
        "description": "Service",
        "quantity": 1,
        "rate": 100.00
      }
    ]
  }'

Next Steps

• Client Endpoints - Client API operations
• Invoice Endpoints - Invoice API operations
• Product Endpoints - Products & Services API operations
• Webhook Endpoints - Webhook API operations
• Error Handling - Handle API errors