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:

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.

Authorization: Bearer YOUR_API_KEY

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

Versioning

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

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.

Pagination

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

Query Parameters

limit · integer · default: "20"

Number of items to return per page. Maximum is 100.

cursor · string

Opaque cursor value from the previous response’s next_cursor field.

Example Response

{
  "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.

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"}'

Use UUID v4 strings for idempotency keys to guarantee uniqueness across clients.

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.

{
  "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.

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.

Next Steps

Workspaces API

Create and manage team workspaces.

Users API

Manage members and roles in workspaces.

Integrations API

Connect and manage external tool integrations.

Events API

Query and subscribe to events from integrations.