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/health

Service 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
  • 200 Serving
  • 503 Down
GET/v1/me

Describe the API key and its organization

Responses
  • 200 OK
  • 401 Missing or invalid API key
  • 403 Scope, origin or suspension prevents access
  • 429 Rate limited
  • 500 Unexpected error (retry with backoff, quote X-Request-Id)
  • 503 Dependency temporarily unavailable (retry with backoff)
POST/v1/uploads

Get 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
  • 201 Created
  • 401 Missing or invalid API key
  • 403 Scope, origin or suspension prevents access
  • 422 Validation error
  • 429 Rate limited
  • 500 Unexpected error (retry with backoff, quote X-Request-Id)
  • 503 Dependency temporarily unavailable (retry with backoff)
POST/v1/jobs

Create a job (1-100 images)

Parameters
  • Idempotency-Key (header)

Body: CreateJob

Responses
  • 200 Replayed idempotent request
  • 202 Accepted: images are queued
  • 401 Missing or invalid API key
  • 402 Not enough credits
  • 403 Scope, origin or suspension prevents access
  • 409 Idempotency-Key reused with a different body
  • 422 Validation error
  • 429 Rate limited
  • 500 Unexpected error (retry with backoff, quote X-Request-Id)
  • 503 Dependency temporarily unavailable (retry with backoff)
GET/v1/jobs

List jobs, newest first

Parameters
  • limit (query)
  • cursor (query): `next_cursor` from the previous page
  • status (query)
Responses
  • 200 OK
  • 401 Missing or invalid API key
  • 403 Scope, origin or suspension prevents access
  • 429 Rate limited
  • 500 Unexpected error (retry with backoff, quote X-Request-Id)
  • 503 Dependency temporarily unavailable (retry with backoff)
GET/v1/jobs/{id}

Get a job with signed image URLs (valid 1 h)

Parameters
  • id (path, required)
Responses
  • 200 OK
  • 401 Missing or invalid API key
  • 403 Scope, origin or suspension prevents access
  • 404 Not found
  • 429 Rate limited
  • 500 Unexpected error (retry with backoff, quote X-Request-Id)
  • 503 Dependency temporarily unavailable (retry with backoff)
POST/v1/jobs/{id}/cancel

Cancel queued images and refund their credits

Parameters
  • id (path, required)
Responses
  • 200 OK
  • 401 Missing or invalid API key
  • 403 Scope, origin or suspension prevents access
  • 404 Not found
  • 409 Job already finished
  • 429 Rate limited
  • 500 Unexpected error (retry with backoff, quote X-Request-Id)
  • 503 Dependency temporarily unavailable (retry with backoff)
GET/v1/images/{id}

Get one image

Parameters
  • id (path, required)
Responses
  • 200 OK
  • 401 Missing or invalid API key
  • 403 Scope, origin or suspension prevents access
  • 404 Not found
  • 429 Rate limited
  • 500 Unexpected error (retry with backoff, quote X-Request-Id)
  • 503 Dependency temporarily unavailable (retry with backoff)
GET/v1/usage

Credit balance and usage for the last 30 days

Responses
  • 200 OK
  • 401 Missing or invalid API key
  • 403 Scope, origin or suspension prevents access
  • 429 Rate limited
  • 500 Unexpected error (retry with backoff, quote X-Request-Id)
  • 503 Dependency temporarily unavailable (retry with backoff)
GET/v1/styles

Available edit styles

Responses
  • 200 OK
  • 401 Missing or invalid API key
  • 403 Scope, origin or suspension prevents access
  • 429 Rate limited
  • 500 Unexpected error (retry with backoff, quote X-Request-Id)
  • 503 Dependency temporarily unavailable (retry with backoff)
GET/v1/webhooks

List webhook endpoints

Responses
  • 200 OK
  • 401 Missing or invalid API key
  • 403 Scope, origin or suspension prevents access
  • 429 Rate limited
  • 500 Unexpected error (retry with backoff, quote X-Request-Id)
  • 503 Dependency temporarily unavailable (retry with backoff)
POST/v1/webhooks

Create a webhook endpoint (secret shown once)

Body: inline object

Responses
  • 201 Created
  • 401 Missing or invalid API key
  • 403 Scope, origin or suspension prevents access
  • 422 Validation error
  • 429 Rate limited
  • 500 Unexpected error (retry with backoff, quote X-Request-Id)
  • 503 Dependency temporarily unavailable (retry with backoff)
DELETE/v1/webhooks/{id}

Delete a webhook endpoint

Parameters
  • id (path, required)
Responses
  • 204 Deleted
  • 401 Missing or invalid API key
  • 403 Scope, origin or suspension prevents access
  • 404 Not found
  • 429 Rate limited
  • 500 Unexpected error (retry with backoff, quote X-Request-Id)
  • 503 Dependency temporarily unavailable (retry with backoff)
POST/v1/webhooks/{id}/test

Send a signed `ping` event

Parameters
  • id (path, required)
Responses
  • 202 Queued
  • 401 Missing or invalid API key
  • 403 Scope, origin or suspension prevents access
  • 404 Not found
  • 429 Rate limited
  • 500 Unexpected error (retry with backoff, quote X-Request-Id)
  • 503 Dependency 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."
    }
  }
}