Getting Started

Get up and running with the Castiz API in under 5 minutes.

1Prerequisites

Before you begin, make sure you have:

A Castiz account. Sign up for free
A workspace created in your Castiz dashboard

2Create an API Key

Generate an API key from your workspace settings:

1Go to Settings → API Keys in your dashboard
2Click Create Key
3Give it a name and select permissions (read/write)
4Copy and save your key securely – it's only shown once!

Keep your API key secure

Never share your API key publicly or commit it to version control. Use environment variables in your applications.

3Authentication

Include your API key in the X-API-Key header of every request:

Request Header

X-API-Key: sk_live_your_api_key_here

API Key Format

API keys start with sk_live_ followed by a unique identifier. The workspace is embedded in the key.

4Base URL

All API requests should be made to:

https://api.castiz.com

5Make Your First API Call

Let's list your videos. The workspace is automatically determined from your API key.

curl -X GET "https://api.castiz.com/videos" \
  -H "X-API-Key: sk_live_your_api_key_here"

Response

200 OK

{
  "success": true,
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "title": "My First Video",
      "status": "ready",
      "duration_seconds": 120,
      "thumbnail_url": "https://...",
      "hls_url": "https://...",
      "created_at": "2024-01-15T10:30:00Z"
    }
  ],
  "pagination": {
    "total": 1,
    "limit": 20,
    "offset": 0
  }
}

6Permissions (Scopes)

API keys have two permission levels:

Scope	Allows
`read`	List and view videos, folders, tags, and player configuration
`write`	Create, update, delete videos, folders, and tags. Upload new videos.

If you try to perform an action without the required scope, you'll receive a 403 error.

Error Handling

All API responses follow a consistent format. Errors include a descriptive message:

Error Response

{
  "detail": {
    "error": "insufficient_scope",
    "message": "This operation requires the 'write' scope",
    "required_scope": "write"
  }
}

Status	Description
`400`	Bad Request - Invalid parameters
`401`	Unauthorized - Invalid or missing API key
`403`	Forbidden - Missing required scope
`404`	Not Found - Resource doesn't exist
`429`	Rate limit exceeded (100 req/min)