> ## Documentation Index
> Fetch the complete documentation index at: https://docs.metabind.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Environments

> API base URLs and response formats

## Base URLs

* **Admin API (REST):** `https://api.metabind.ai/app/v1`
* **Client API (REST):** `https://api.metabind.ai/api/v1`
* **GraphQL API:** `https://api.metabind.ai/graphql`
* **CDN:** `https://cdn.metabind.ai`

## URL Structure

### REST API Path Pattern

All REST API endpoints follow this pattern:

```
https://api.metabind.ai/app/v1/organizations/{organizationId}/projects/{projectId}/[resource]
```

Example paths:

| Resource        | Path                                                            |
| --------------- | --------------------------------------------------------------- |
| List components | `/app/v1/organizations/org123/projects/proj456/components`      |
| Get content     | `/app/v1/organizations/org123/projects/proj456/content/cont789` |
| Upload asset    | `/app/v1/organizations/org123/projects/proj456/assets`          |
| Create package  | `/app/v1/organizations/org123/projects/proj456/packages`        |

### CDN Asset URLs

Assets are served from the CDN with this pattern:

```
https://cdn.metabind.ai/{organizationId}/{projectId}/assets/{assetId}/{filename}
```

## API Versioning

The API uses semantic versioning in the URL path (e.g., `/app/v1/`).

| Version | Status  | Description                             |
| ------- | ------- | --------------------------------------- |
| `v1`    | Current | Initial release with core functionality |

### Versioning Policy

* **Breaking changes** are introduced in new major versions (`v2`, `v3`, etc.)
* **Backward-compatible changes** may be added to existing versions
* **Deprecated features** will be announced with a migration timeline
* **Old versions** will be supported for at least 12 months after a new major version

## Response Format

All successful responses follow a consistent format:

```json theme={null}
{
  "data": {
    // Response data
  },
  "meta": {
    "requestId": "unique-request-identifier",
    "timestamp": "2024-03-21T10:00:00Z"
  }
}
```

### Paginated Responses

List endpoints use one of two pagination styles:

#### Cursor-Based Pagination

Used by content-heavy endpoints (content, components, assets, packages):

```json theme={null}
{
  "data": [
    { "id": "item1", "name": "First Item" },
    { "id": "item2", "name": "Second Item" }
  ],
  "pagination": {
    "lastKey": "encoded-pagination-key"
  }
}
```

| Parameter | Type   | Default | Description                                 |
| --------- | ------ | ------- | ------------------------------------------- |
| `limit`   | number | 10      | Items per page (max: 100)                   |
| `lastKey` | string | -       | Cursor from previous response for next page |

#### Offset-Based Pagination

Used by organizational endpoints (tags, api-keys):

```json theme={null}
{
  "data": [
    { "id": "user1", "name": "Jane Doe" },
    { "id": "user2", "name": "John Smith" }
  ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 45
  }
}
```

| Parameter | Type   | Default | Description               |
| --------- | ------ | ------- | ------------------------- |
| `page`    | number | 1       | Page number (1-indexed)   |
| `limit`   | number | 20      | Items per page (max: 100) |

## Request Headers

### Required Headers

**Admin API** (`/app/v1/...`):

```http theme={null}
Authorization: Bearer YOUR_JWT
Content-Type: application/json
```

**Client API** (`/api/v1/...`):

```http theme={null}
x-api-key: YOUR_API_KEY
Content-Type: application/json
```

### Optional Headers

| Header            | Description                           |
| ----------------- | ------------------------------------- |
| `Accept-Language` | Preferred response language           |
| `X-Request-ID`    | Custom request identifier for tracing |

## Configuring Your Application

### Environment Variables

```bash theme={null}
METABIND_API_URL=https://api.metabind.ai/app/v1
METABIND_CDN_URL=https://cdn.metabind.ai
```

### JavaScript Example

```javascript theme={null}
const config = {
  apiUrl: process.env.METABIND_API_URL || 'https://api.metabind.ai/app/v1',
  cdnUrl: process.env.METABIND_CDN_URL || 'https://cdn.metabind.ai',
  jwt: process.env.METABIND_JWT
};

class MetabindClient {
  constructor(config) {
    this.apiUrl = config.apiUrl;
    this.cdnUrl = config.cdnUrl;
    this.jwt = config.jwt;
  }

  async getContent(orgId, projectId, contentId) {
    const url = `${this.apiUrl}/organizations/${orgId}/projects/${projectId}/content/${contentId}`;
    const response = await fetch(url, {
      headers: {
        'Authorization': `Bearer ${this.jwt}`,
        'Content-Type': 'application/json'
      }
    });
    return response.json();
  }
}
```

## Health Check

```http theme={null}
GET https://api.metabind.ai/health
```

Response:

```json theme={null}
{
  "status": "healthy",
  "version": "1.0.0",
  "timestamp": "2024-03-21T10:00:00Z"
}
```