API reference
Version 1.0.0. Base URL https://api.shotedit.com. Machine-readable spec: openapi.json (import it in Postman, Insomnia or a code generator).
The ShotEdit API turns raw property photos into listing-ready images: exposure and color, vertical correction, sky replacement, window pull and optional face/plate blur.
**Flow**: create a job with image URLs (or `upload_id`s from `POST /v1/uploads`), then receive a signed `job.completed` webhook or poll `GET /v1/jobs/{id}`.
**Auth**: `Authorization: Bearer se_live_...`. Test keys (`se_test_...`) are free, watermarked and never charge credits.
**Billing**: 1 credit per image, reserved when the job is created and refunded automatically if processing fails.
**Idempotency**: send `Idempotency-Key` on `POST /v1/jobs`; retries with the same key and body return the original job.
**Errors**: RFC 9457 `application/problem+json` with a stable `code`; the catalog is at https://shotedit.com/docs#errors. Retry only 429, 500 and 503.
**Versioning**: `/v1` only changes additively (new endpoints, optional fields, event types, error codes). Ignore unknown fields.
**Pagination**: `limit` + `cursor`; responses are `{ object: "list", data, has_more, next_cursor }`.
**Large files**: never send image bytes to the API. `POST /v1/uploads` returns a signed URL; `PUT` the file there directly (up to 60 MB).
**Rate limits**: per key and per minute, by plan. Every response carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`.
**Webhooks**: `ShotEdit-Signature: t=<unix>,v1=<hex>` where `v1 = HMAC_SHA256(secret, "<t>.<raw body>")`. Reject timestamps older than 5 minutes. Failed deliveries are retried 7 times over ~24 h.GET
/v1/healthService health (no key needed)
`200` while the API can serve requests (each component `ok` or `degraded`); `503` when it cannot. Never cached. Human view: https://shotedit.com/status.
Responses
200Serving503Down
GET
/v1/meDescribe the API key and its organization
Responses
200OK401Missing or invalid API key403Scope, origin or suspension prevents access429Rate limited500Unexpected error (retry with backoff, quote X-Request-Id)503Dependency temporarily unavailable (retry with backoff)
POST
/v1/uploadsGet a signed URL to upload a file
Returns an `upload_url`. `PUT` the raw file bytes there with the same `Content-Type`, then use the `id` as `upload_id` in a job. Uploads expire after 24 h if unused.
Body: inline object
Responses
201Created401Missing or invalid API key403Scope, origin or suspension prevents access422Validation error429Rate limited500Unexpected error (retry with backoff, quote X-Request-Id)503Dependency temporarily unavailable (retry with backoff)
POST
/v1/jobsCreate a job (1-100 images)
Parameters
Idempotency-Key(header)
Body: CreateJob
Responses
200Replayed idempotent request202Accepted: images are queued401Missing or invalid API key402Not enough credits403Scope, origin or suspension prevents access409Idempotency-Key reused with a different body422Validation error429Rate limited500Unexpected error (retry with backoff, quote X-Request-Id)503Dependency temporarily unavailable (retry with backoff)
GET
/v1/jobsList jobs, newest first
Parameters
limit(query)cursor(query): `next_cursor` from the previous pagestatus(query)
Responses
200OK401Missing or invalid API key403Scope, origin or suspension prevents access429Rate limited500Unexpected error (retry with backoff, quote X-Request-Id)503Dependency temporarily unavailable (retry with backoff)
GET
/v1/jobs/{id}Get a job with signed image URLs (valid 1 h)
Parameters
id(path, required)
Responses
200OK401Missing or invalid API key403Scope, origin or suspension prevents access404Not found429Rate limited500Unexpected error (retry with backoff, quote X-Request-Id)503Dependency temporarily unavailable (retry with backoff)
POST
/v1/jobs/{id}/cancelCancel queued images and refund their credits
Parameters
id(path, required)
Responses
200OK401Missing or invalid API key403Scope, origin or suspension prevents access404Not found409Job already finished429Rate limited500Unexpected error (retry with backoff, quote X-Request-Id)503Dependency temporarily unavailable (retry with backoff)
GET
/v1/images/{id}Get one image
Parameters
id(path, required)
Responses
200OK401Missing or invalid API key403Scope, origin or suspension prevents access404Not found429Rate limited500Unexpected error (retry with backoff, quote X-Request-Id)503Dependency temporarily unavailable (retry with backoff)
GET
/v1/usageCredit balance and usage for the last 30 days
Responses
200OK401Missing or invalid API key403Scope, origin or suspension prevents access429Rate limited500Unexpected error (retry with backoff, quote X-Request-Id)503Dependency temporarily unavailable (retry with backoff)
GET
/v1/stylesAvailable edit styles
Responses
200OK401Missing or invalid API key403Scope, origin or suspension prevents access429Rate limited500Unexpected error (retry with backoff, quote X-Request-Id)503Dependency temporarily unavailable (retry with backoff)
GET
/v1/webhooksList webhook endpoints
Responses
200OK401Missing or invalid API key403Scope, origin or suspension prevents access429Rate limited500Unexpected error (retry with backoff, quote X-Request-Id)503Dependency temporarily unavailable (retry with backoff)
POST
/v1/webhooksCreate a webhook endpoint (secret shown once)
Body: inline object
Responses
201Created401Missing or invalid API key403Scope, origin or suspension prevents access422Validation error429Rate limited500Unexpected error (retry with backoff, quote X-Request-Id)503Dependency temporarily unavailable (retry with backoff)
DELETE
/v1/webhooks/{id}Delete a webhook endpoint
Parameters
id(path, required)
Responses
204Deleted401Missing or invalid API key403Scope, origin or suspension prevents access404Not found429Rate limited500Unexpected error (retry with backoff, quote X-Request-Id)503Dependency temporarily unavailable (retry with backoff)
POST
/v1/webhooks/{id}/testSend a signed `ping` event
Parameters
id(path, required)
Responses
202Queued401Missing or invalid API key403Scope, origin or suspension prevents access404Not found429Rate limited500Unexpected error (retry with backoff, quote X-Request-Id)503Dependency temporarily unavailable (retry with backoff)
Schemas
Problem
{
"type": "object",
"required": [
"status",
"code",
"detail"
],
"properties": {
"type": {
"type": "string",
"format": "uri",
"description": "Link to the documentation of this code."
},
"title": {
"type": "string"
},
"status": {
"type": "integer"
},
"code": {
"type": "string",
"description": "Stable machine-readable code (see /docs#errors). New codes may be added within v1."
},
"detail": {
"type": "string",
"description": "Human-readable; may change."
},
"errors": {
"type": "array",
"items": {
"type": "object",
"properties": {
"path": {
"type": "string"
},
"message": {
"type": "string"
}
}
}
}
}
}Health
{
"type": "object",
"required": [
"status",
"checks"
],
"properties": {
"status": {
"type": "string",
"enum": [
"ok",
"degraded",
"down"
]
},
"version": {
"type": "string"
},
"region": {
"type": [
"string",
"null"
]
},
"time": {
"type": "string",
"format": "date-time"
},
"checks": {
"type": "object",
"additionalProperties": {
"type": "object",
"required": [
"status"
],
"properties": {
"status": {
"type": "string",
"enum": [
"ok",
"degraded",
"down"
]
}
}
}
}
}
}JobStatus
{
"type": "string",
"enum": [
"queued",
"processing",
"completed",
"partial",
"failed",
"canceled"
]
}ImageStatus
{
"type": "string",
"enum": [
"pending",
"queued",
"processing",
"completed",
"failed",
"canceled"
]
}EventType
{
"type": "string",
"enum": [
"job.completed",
"job.failed",
"image.completed",
"image.failed"
]
}EditOptions
{
"type": "object",
"additionalProperties": false,
"properties": {
"style": {
"type": "string",
"enum": [
"natural",
"bright",
"warm",
"vivid",
"house"
],
"default": "natural",
"description": "`house` applies your organization house style (Pro and above)."
},
"vertical_correction": {
"type": "boolean",
"default": true
},
"sky": {
"type": "string",
"enum": [
"auto",
"off"
],
"default": "auto"
},
"window_pull": {
"type": "boolean",
"default": true
},
"facade_air": {
"type": "boolean",
"default": false,
"description": "Adds breathing room around full facades."
},
"privacy_blur": {
"type": "string",
"enum": [
"off",
"faces_plates"
],
"default": "off"
},
"output": {
"type": "object",
"properties": {
"format": {
"type": "string",
"enum": [
"jpeg",
"webp"
],
"default": "jpeg"
},
"quality": {
"type": "integer",
"minimum": 60,
"maximum": 100,
"default": 92
},
"max_width": {
"type": "integer",
"minimum": 320,
"maximum": 12000
}
}
}
}
}CreateJob
{
"type": "object",
"required": [
"images"
],
"additionalProperties": false,
"properties": {
"images": {
"type": "array",
"minItems": 1,
"maxItems": 100,
"items": {
"oneOf": [
{
"type": "object",
"required": [
"url"
],
"properties": {
"url": {
"type": "string",
"format": "uri"
},
"filename": {
"type": "string"
}
}
},
{
"type": "object",
"required": [
"upload_id"
],
"properties": {
"upload_id": {
"type": "string",
"format": "uuid"
},
"filename": {
"type": "string"
}
}
}
]
}
},
"options": {
"$ref": "#/components/schemas/EditOptions"
},
"webhook_url": {
"type": "string",
"format": "uri",
"pattern": "^https://",
"description": "Receives job.* and image.* events for this job, signed with your organization signing secret."
},
"metadata": {
"type": "object",
"maxProperties": 20,
"additionalProperties": {
"type": [
"string",
"number",
"boolean",
"null"
]
},
"description": "Returned untouched in the job and its events (e.g. your listing id)."
}
}
}Image
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"object": {
"const": "image"
},
"status": {
"$ref": "#/components/schemas/ImageStatus"
},
"position": {
"type": "integer"
},
"filename": {
"type": [
"string",
"null"
]
},
"width": {
"type": [
"integer",
"null"
]
},
"height": {
"type": [
"integer",
"null"
]
},
"processing_ms": {
"type": [
"integer",
"null"
]
},
"error": {
"type": [
"object",
"null"
],
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
}
}
},
"warnings": {
"type": "array",
"description": "Steps skipped or downgraded on a delivered photo (e.g. privacy_blur_unavailable).",
"items": {
"type": "object",
"properties": {
"code": {
"type": "string"
},
"message": {
"type": "string"
}
}
}
},
"original_url": {
"type": [
"string",
"null"
]
},
"output_url": {
"type": [
"string",
"null"
],
"description": "Signed, valid for 1 hour"
},
"preview_url": {
"type": [
"string",
"null"
]
}
}
}JobSummary
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"object": {
"const": "job"
},
"status": {
"$ref": "#/components/schemas/JobStatus"
},
"environment": {
"type": "string",
"enum": [
"live",
"test"
]
},
"counts": {
"type": "object",
"properties": {
"total": {
"type": "integer"
},
"completed": {
"type": "integer"
},
"failed": {
"type": "integer"
}
}
},
"metadata": {
"type": "object"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"completed_at": {
"type": [
"string",
"null"
],
"format": "date-time"
}
}
}Job
{
"allOf": [
{
"$ref": "#/components/schemas/JobSummary"
},
{
"type": "object",
"properties": {
"source": {
"type": "string"
},
"options": {
"$ref": "#/components/schemas/EditOptions"
},
"images": {
"type": "array",
"items": {
"$ref": "#/components/schemas/Image"
}
}
}
}
]
}Upload
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"object": {
"const": "upload"
},
"upload_url": {
"type": "string"
},
"method": {
"const": "PUT"
},
"headers": {
"type": "object"
},
"expires_at": {
"type": "string",
"format": "date-time"
}
}
}Me
{
"type": "object",
"properties": {
"key": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"kind": {
"type": "string"
},
"environment": {
"type": "string"
},
"scopes": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"organization": {
"type": "object",
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"plan": {
"type": "string"
}
}
},
"credits": {
"type": "integer"
},
"rate_limit_per_min": {
"type": "integer"
}
}
}Usage
{
"type": "object",
"properties": {
"plan": {
"type": "string"
},
"balance": {
"type": "integer"
},
"billing_organization_id": {
"type": "string"
},
"last_30_days": {
"type": "object",
"properties": {
"images": {
"type": "integer"
},
"failed": {
"type": "integer"
}
}
},
"daily": {
"type": "array",
"items": {
"type": "object",
"properties": {
"day": {
"type": "string",
"format": "date"
},
"images": {
"type": "integer"
}
}
}
}
}
}WebhookEndpoint
{
"type": "object",
"properties": {
"id": {
"type": "string",
"format": "uuid"
},
"url": {
"type": "string"
},
"description": {
"type": [
"string",
"null"
]
},
"events": {
"type": "array",
"items": {
"$ref": "#/components/schemas/EventType"
}
},
"active": {
"type": "boolean"
},
"created_at": {
"type": "string",
"format": "date-time"
}
}
}Event
{
"type": "object",
"properties": {
"id": {
"type": "string",
"example": "evt_..."
},
"type": {
"$ref": "#/components/schemas/EventType"
},
"created_at": {
"type": "string",
"format": "date-time"
},
"data": {
"type": "object",
"description": "job.*: a JobSummary plus `images` [{id, status, error}]. image.*: an Image without URLs plus `job_id` and `metadata`. Fetch GET /v1/jobs/{id} for fresh signed URLs."
}
}
}