# Vremly API

> Vremly is a real-estate media production platform. Its REST API covers
> projects (shoots), customers, media delivery, invoicing and webhooks. This
> file is the machine-readable index of the developer documentation, following
> the llms.txt convention.

Base URL: `https://api.vremly.com`

## Authenticating

Two credentials. Integrations should use an API key.

- **API key** — send `x-api-key: <key>`. Belongs to one organization; the server
  derives the org from the key, so `x-org-id` is not required and is ignored if
  sent. Scoped: `READ` covers GET/HEAD/OPTIONS, `WRITE` covers mutations and
  implies READ, `ADMIN` covers everything, `BULK_IMPORT` and `WEBHOOKS` are
  narrow and do not grant general writes. A missing scope returns 403 naming
  what was needed and what the key holds.
- **JWT bearer** — send `Authorization: Bearer <token>` plus `x-org-id: <id>`.
  Identifies a person, expires, and is the wrong choice for a server.

## Rate limits

Three windows apply simultaneously: 3 requests/second, 20 per 10 seconds, 100
per minute. The burst limit is the one most callers hit first. API-key traffic
is bucketed **per key**, not per IP, so hosted automation platforms sharing
egress addresses do not compete for one allowance. Bearer-authenticated requests
are not rate limited. Responses carry `X-RateLimit-Limit`,
`X-RateLimit-Remaining` and `X-RateLimit-Reset`; a 429 carries `Retry-After`.

## Webhooks

Register at `POST /webhooks/subscriptions`. Events are upper snake case:
`PROJECT_CREATED`, `PROJECT_ASSIGNED`, `PROJECT_STATUS_CHANGED`,
`PROJECT_DELIVERED`, `DELIVERY_APPROVED`, `INVOICE_CREATED`, `INVOICE_SENT`,
`INVOICE_PAID`, `INVOICE_VOIDED`, `CUSTOMER_CREATED`, `CUSTOMER_UPDATED`.

`PROJECT_DELIVERED` fires when the company sends the work; `DELIVERY_APPROVED`
fires when the client accepts it. They are different moments and a sent delivery
can still come back as a revision request.

Signature: `X-Webhook-Signature: t=<unix-seconds>,v1=<hmac>`, an HMAC-SHA256 over
the string `timestamp` + `.` + `rawBody`, keyed with the subscription secret, hex
encoded. Verify against the raw bytes, not a re-serialised object. Delivery is
at-least-once — deduplicate on the `id` field.

## Docs

- [Overview](https://docs.vremly.com/guides/): what the API covers.
- [Getting Started](https://docs.vremly.com/guides/getting-started): first request.
- [Authentication](https://docs.vremly.com/guides/authentication): API keys, scopes, bearer tokens, refresh.
- [Organization Context](https://docs.vremly.com/guides/organization-context): the `x-org-id` header and when it is needed.
- [Projects Workflow](https://docs.vremly.com/guides/projects-workflow): the shoot lifecycle and its statuses.
- [Media Management](https://docs.vremly.com/guides/media-management): uploading, variants and delivery.
- [Webhooks](https://docs.vremly.com/guides/webhooks): events, payloads, signature verification, retries.
- [MCP Server](https://docs.vremly.com/guides/mcp): the Model Context Protocol server, for agents that would rather call tools than construct HTTP.
- [Error Handling](https://docs.vremly.com/guides/error-handling): status codes and error shapes.
- [Rate Limits](https://docs.vremly.com/guides/rate-limits): windows, buckets and backoff.
- [Troubleshooting](https://docs.vremly.com/guides/troubleshooting): common failures.

## API reference

- [OpenAPI specification](https://docs.vremly.com/openapi/openapi.json): the
  complete machine-readable contract, 854 routes. Generated from the backend's
  own source rather than written by hand, so it is the authority whenever this
  file or a guide disagrees with it. Regenerated on release, not per request —
  if an endpoint here does not behave as described, trust the server.

## MCP

There is a Model Context Protocol server at
https://github.com/RelayDigital/vremly-mcp, installable with
`npx -y github:RelayDigital/vremly-mcp` and configured with a `VREMLY_API_KEY`
environment variable. Three tools — `vremly_search_endpoints`,
`vremly_describe_endpoint`, `vremly_request` — cover every operation without a
per-endpoint tool list. It authenticates with the same `x-api-key`, and the
key's scopes are enforced server-side, so a READ key cannot write regardless of
what the agent is instructed to do.

## Notes for agents

- Read the OpenAPI spec rather than inferring routes from these summaries.
- Never place an API key in a URL or query string; it belongs in the `x-api-key`
  header.
- A 403 mentioning a scope is a credential problem, not a permissions bug —
  the key needs re-issuing with the scope named in the message.
- Respect `Retry-After` on 429 and back off; the burst limit is 3 per second.