API

Use the in-app viewer for exact schemas, parameters, and example responses:

• OpenAPI viewer

Current limitation: the published OpenAPI spec does not yet declare endpoint auth requirements. Use the guidance below for API key setup and testing until auth metadata is added to the schema.

Create keys from Settings:

1. Open /settings?tab=api-key.
2. Create a named key for the script, service, or environment that will use it.
3. Copy the secret immediately. It is shown only once.

   Operational rules:

   • Treat each key like a password and store it in a secret manager or environment variable.
   • Use separate keys for local development, preview automation, and production jobs.
   • Revoke keys you no longer need instead of reusing old shared credentials.

For API key-based requests, send:

Authorization: Bearer <API_KEY>
Content-Type: application/json

Example:

curl https://api.d1v.ai/api/... \
  -H 'Authorization: Bearer $D1V_API_KEY' \
  -H 'Content-Type: application/json'

API keys are intended for non-admin endpoints. Admin routes still require normal user authentication.

The OpenAPI page supports Swagger UI authorization flow:

1. Open OpenAPI viewer.
2. Click Authorize.
3. Paste Bearer <API_KEY> unless the dialog already prefixes Bearer for you.
4. Run Try it out on the target endpoint.

   Use the viewer to inspect path params, query params, request bodies, and sample responses before wiring a real client.

Today, endpoint auth scope is not discoverable from the OpenAPI schema itself.

• Public: may not require auth.
• Supports API key: generally safe target for server-to-server usage.
• Requires user auth: expects a signed-in user session or user token.
• Admin only: should not be exposed in public integration docs.

Until the schema is annotated, verify access by checking the product flow, testing in the OpenAPI viewer, and confirming whether the route is meant for non-admin usage.

Common envelope:

{
  "code": 0,
  "msg": "OK",
  "data": {}
}

• code === 0 usually indicates success.
• Some endpoints may also return a detail field for validation-style errors.

Follow OpenAPI per endpoint. Common patterns:

• ?limit=20&offset=0
• ?page=1&page_size=20

Filtering is typically done with query params, for example: ?environment=dev

1. Verify signatures
2. Enforce idempotency by event id
3. Expect duplicates (at-least-once delivery)

• For 429, back off with exponential delays and jitter.
• For 5xx, retry carefully and log useful fields (code, msg, detail).

Common API key troubleshooting:

• 401 Unauthorized: key is missing, malformed, revoked, or sent with the wrong Bearer format.
• 403 Forbidden: the route exists, but your key or user does not have permission for that operation.
• 429 Too Many Requests: reduce concurrency, add backoff, and avoid hot retry loops.
• 5xx: capture request id / response body, then retry only idempotent calls.

Use a simple rotation procedure:

1. Create a new key in /settings?tab=api-key.
2. Deploy or update clients to use the new key.
3. Verify traffic with the new key.
4. Revoke the old key immediately after cutover.

   Do not overwrite a key in place. Rotate by replacement so rollback and auditing stay clear.