API Overview

REST API basics -- base URL, versioning, rate limits, and response format.

The Demoship API is a RESTful JSON API for managing demos, analytics, shares, and team members programmatically.

Base URL

All API requests use the following base URL:

https://api.demoship.com/v1

Versioning

The API is versioned via the URL path. The current version is v1. When breaking changes are introduced, a new version will be released. Previous versions remain available for at least 12 months after a new version launches.

Authentication

All requests require authentication via API key or OAuth 2.0 bearer token. See Authentication for details.

Request format

• Use Content-Type: application/json for request bodies
• Query parameters for filtering and pagination
• All timestamps are in ISO 8601 format (UTC)

Response format

Successful responses return JSON with a consistent structure:

{
  "data": { ... },
  "meta": {
    "request_id": "req_abc123"
  }
}

List endpoints return paginated results:

{
  "data": [ ... ],
  "meta": {
    "total": 42,
    "page": 1,
    "per_page": 20,
    "request_id": "req_abc123"
  }
}

Error format

Errors return an appropriate HTTP status code with a JSON body:

{
  "error": {
    "code": "not_found",
    "message": "Demo not found",
    "request_id": "req_abc123"
  }
}

Common status codes:

Rate limits

API requests are rate limited per API key:

Rate limit headers are included in every response:

• X-RateLimit-Limit -- Maximum requests per minute
• X-RateLimit-Remaining -- Requests remaining in the current window
• X-RateLimit-Reset -- Unix timestamp when the window resets

When rate limited, wait until the reset time before retrying.