API and AI assistants

Configuration
Public API operations

Use the REST API at /api/v1 or connect an assistant to /mcp. Both enforce your current team permissions. Saved variable values and agent credentials are never returned; log access is separate because output may contain secrets.

Create an API key

Open Account → API keys → Create API key. Select the team, optional project, Read only/Deploy/Manage access, log permission and expiry. The default lifetime is 30 days.

Copy the value once into your integration's secret manager. Revoke stops access; Rotate immediately invalidates the previous key. Removing a membership invalidates its credentials; rejoining does not revive them.

curl "$DEVPUSH_URL/api/v1/projects?limit=25" \
  -H "Authorization: Bearer $DEVPUSH_API_KEY"

REST accepts API keys, not browser cookies or MCP OAuth tokens. The operation reference lists scopes and supported actions. Your installation's /api/v1/openapi.json supplies the actual request/response schemas.

Connect an assistant

Copy the URL from Account → Connected apps, usually https://YOUR-DEVPUSH-HOST/mcp. Add it to a client supporting remote HTTP MCP.

  • Browser sign-in: approve the team, optional project and permissions. Manage/revoke the resulting 30-day grant in Connected apps.
  • API key: supply Authorization: Bearer KEY if the client supports custom headers. Manage it under API keys; it does not create a Connected apps entry.

Check the callback host on consent screens. Cloud-hosted assistants cannot reach localhost. Node and Workers support dynamic client registration; metadata-discovery-only clients work on Node, not Workers. Changing DEVPUSH_MCP_URL requires OAuth clients to reconnect.

Requests and pagination

Send JSON for writes. Lists return items and nextCursor; follow cursors until null, including after empty filtered pages. Pages default to 25 items, maximum 100. Request bodies are limited to 128 KiB; unknown fields are rejected.

Keys and OAuth grants never exceed their issued scopes/role or current membership. Project-restricted credentials cannot manage whole-team resources. See operations for additional owner/admin requirements.

Writes and retries

Every REST write needs a unique Idempotency-Key; MCP uses idempotencyKey. Reuse the same key and identical payload when retrying the same action. Different input returns IDEMPOTENCY_CONFLICT. Replay records last at least 24 hours, not indefinitely.

curl "$DEVPUSH_URL/api/v1/projects/PROJECT_ID/deployments" \
  -H "Authorization: Bearer $DEVPUSH_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  --data '{"environmentId":"ENVIRONMENT_ID","branch":"main"}'

Acceptance is not execution success: retain the returned deployment/job ID and poll its status. When an outcome is uncertain, inspect history before creating a new action.

Configuration writes require the latest settingsVersion. HTTP 409 SETTINGS_CONFLICT means read current settings and review changes before resubmitting. Destructive actions require the confirmations in their schemas.

Errors and limits

Errors contain error.code, message and requestId. Keep the request ID when reporting failures. Honor Retry-After on HTTP 429. Resource budgets allow 120 reads/minute per membership and 20 writes/minute per membership and operation. Transport limits also apply.

Logs have bounded pages and may be truncated or removed by retention. Do not treat the API as an archival log drain.