POST /api/v1/deployments declares a deployment. Use it when monocle deploy doesn't fit your pipeline.
Request
curl -X POST https://api.monocle.sh/api/v1/deployments \
-H "x-api-key: $MONOCLE_API_KEY" \
-H "content-type: application/json" \
-d '{
"service": "api",
"environment": "production",
"version": "1.8.2",
"commitSha": "a1b2c3d4e5f60718293a4b5c6d7e8f9012345678",
"status": "succeeded",
"externalId": "github:acme/shop:123456789:1:api:production"
}'Authenticate with a deploy key in the x-api-key header. Project API keys created before deploy keys also work. DSNs and browser keys are refused, because they can be public. Each key can send 60 requests per minute.
| Field | Description |
|---|---|
service | Required. The service.name of the service. Unknown services are accepted. |
environment | Required. The environment slug. It must exist. |
version | The release version, up to 255 characters. version or commitSha is required. |
commitSha | The commit, 7 to 40 hexadecimal characters |
status | started, succeeded (default), failed, or canceled |
startedAt, finishedAt | ISO 8601 dates. Without them, Monocle uses the time it receives the request. |
externalId | Your identifier for this deployment, up to 255 characters. Makes the call idempotent. |
actor, ciUrl | Who deployed, and a link to the CI run |
repositoryUrl, metadata | The repository URL, and a JSON object of up to 4 KB |
When only a commit is sent, Monocle matches it with the release that reported this commit in its telemetry. A service versioned in semver that emits vcs.ref.head.revision is therefore matched by its SHA.
Statuses and idempotence
With the same externalId, a call updates the same deployment. A started deployment can become succeeded, failed, or canceled. Those three statuses are final. Sending the same status again is accepted, and any other change is refused. Without externalId, each call creates a deployment.
Failed and canceled deployments stay in the history but don't appear on charts, because they didn't change the code in service.
Responses
| Status | Meaning |
|---|---|
201 | Deployment declared |
200 | Existing deployment updated, or same status sent again |
401 | Missing, invalid, or revoked key, or a key that can't declare deployments |
409 | Refused status change, or externalId used by another service or environment |
422 | Invalid payload, unknown environment (the response lists the available slugs), or a short commitSha that matches several commits |
429 | Rate limit reached |
A successful response contains the deployment id, its source (api or cli), its status, merged (whether it is tied to a detected deployment), and its url in Monocle.