> ## Documentation Index
> Fetch the complete documentation index at: https://moonshadow-ep3.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Moonshadow REST API Reference Overview

> Base URL, authentication, versioning, pagination, idempotency, and error handling for the Moonshadow REST API at api.moonshadow.dev/v1.

The Moonshadow REST API lets you programmatically manage workspaces, users, integrations, and events. This page covers the fundamentals you need before making your first call, including the base URL, how to authenticate, how responses are paginated, and how to safely retry requests without side effects.

## Base URL

All API requests use the following base URL:

```text theme={null}
https://api.moonshadow.dev/v1
```

Send requests over HTTPS only. Unencrypted HTTP requests are rejected.

## Authentication

Authenticate every request with an API key using the `Authorization` header in Bearer format. You can create and manage API keys from your Moonshadow dashboard under **Settings > API Keys**.

```text theme={null}
Authorization: Bearer YOUR_API_KEY
```

<Warning>
  Treat your API keys like passwords. Do not commit them to version control or expose them in client-side code.
</Warning>

## Versioning

The current API version is `v1`. The version is part of the base URL:

```text theme={null}
https://api.moonshadow.dev/v1
```

Moonshadow follows a deprecation policy for API changes. When a breaking change is introduced, a new version is released and the previous version is supported for at least 6 months. Deprecation notices are posted in the [Changelog](/reference/changelog).

## Pagination

List endpoints return collections using cursor-based pagination. Include a `cursor` query parameter to fetch the next page of results.

### Query Parameters

<ParamField query="limit" default="20" type="integer">
  Number of items to return per page. Maximum is 100.
</ParamField>

<ParamField query="cursor" type="string">
  Opaque cursor value from the previous response's `next_cursor` field.
</ParamField>

### Example Response

```json theme={null}
{
  "data": [
    { "id": "ws_123", "name": "Engineering", "slug": "engineering" },
    { "id": "ws_456", "name": "Design", "slug": "design" }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6IndzXzQ1NiJ9",
    "has_more": true
  }
}
```

When `has_more` is `false`, you have reached the final page.

## Idempotency

To safely retry requests without creating duplicate resources, include an `Idempotency-Key` header with a unique client-generated identifier. Moonshadow stores the response for 24 hours and returns the cached result for duplicate keys.

```bash theme={null}
curl -X POST https://api.moonshadow.dev/v1/workspaces \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000" \
  -H "Content-Type: application/json" \
  -d '{"name": "Marketing", "slug": "marketing"}'
```

<Tip>
  Use UUID v4 strings for idempotency keys to guarantee uniqueness across clients.
</Tip>

## Content Type

All request bodies must be valid JSON with the `Content-Type: application/json` header. Responses are returned as JSON.

## Errors

Moonshadow uses conventional HTTP status codes. Error responses include a JSON body with `error` and `message` fields.

```json theme={null}
{
  "error": "workspace_not_found",
  "message": "The requested workspace does not exist or you do not have access.",
  "status_code": 404
}
```

For a full list of error codes, retry guidance, and status code meanings, see the [Errors Reference](/reference/errors).

## Rate Limits

The API enforces a rate limit of 1000 requests per minute per workspace. Exceeding this limit returns a `429 Too Many Requests` response. For details, see [Rate Limits](/reference/rate-limits).

## Next Steps

<CardGroup cols={2}>
  <Card title="Workspaces API" href="/api-reference/workspaces">
    Create and manage team workspaces.
  </Card>

  <Card title="Users API" href="/api-reference/users">
    Manage members and roles in workspaces.
  </Card>

  <Card title="Integrations API" href="/api-reference/integrations">
    Connect and manage external tool integrations.
  </Card>

  <Card title="Events API" href="/api-reference/events">
    Query and subscribe to events from integrations.
  </Card>
</CardGroup>