openapi: 3.1.0
info:
  title: Renderspace API
  version: 1.0.0
  summary: Turn a job-site photo into a photorealistic design concept.
  description: |
    Public REST API for Renderspace. Authenticate with an API key created from a
    Professional or Business account.

    **Credits:** Each successful `POST /renders` charges **2 credits**
    (`API_RENDER_CREDIT_COST`). Failed validation or auth errors do not charge.
    Check balance with `GET /credits`. Responses may include `X-Credits-Remaining`.

    **Webhooks:** Register HTTPS completion endpoints via session-auth `POST /webhooks`
    (Pro/Business). After each API render reaches `completed` or `failed`, Renderspace
    fire-and-forget POSTs a signed JSON body with headers `X-Renderspace-Event`
    (`render.completed` | `render.failed`), `X-Renderspace-Timestamp` (unix seconds) and
    `X-Renderspace-Signature: sha256=<hex>` = HMAC-SHA256(secret, `<timestamp>.<raw body>`).
    Reject deliveries whose timestamp is more than 5 minutes old. One attempt, no retries.
    `POST /renders` remains synchronous for clients; webhook delivery never blocks or
    fails the render HTTP response. Async create mode is not in this phase.

    **CORS:** Bearer-key routes (`/credits`, `/renders`) support browser CORS.
    Set `PUBLIC_API_CORS_ORIGINS` to a comma-separated allowlist, or leave unset
    for `Access-Control-Allow-Origin: *` (no credentials). Cookie session routes
    (`/keys`, `/webhooks`, `/usage`) remain same-origin.

    **Rate limits:** 60 requests/minute per API key. Responses include
    `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-RateLimit-Reset`; `429` adds
    `Retry-After`. If the rate limiter is misconfigured or unreachable the API answers
    `503 configuration_error` rather than serving unlimited traffic.

    Keep this file identical to `public/openapi/v1.yaml` (served at `/openapi/v1.yaml`).
  contact:
    name: Renderspace
    url: https://www.renderspace.ai/developers
  license:
    name: Proprietary
servers:
  - url: https://www.renderspace.ai/api/v1
    description: Production
security:
  - bearerAuth: []
  - apiKeyHeader: []
tags:
  - name: Renders
  - name: Credits
  - name: Keys
  - name: Webhooks
paths:
  /credits:
    get:
      tags: [Credits]
      summary: Get remaining credits
      operationId: getCredits
      description: Returns the caller's plan and credit balance. Does not consume credits.
      responses:
        "200":
          description: Credit balance
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Credits"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/RateLimited"
  /renders:
    get:
      tags: [Renders]
      summary: List recent renders
      operationId: listRenders
      parameters:
        - in: query
          name: limit
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 20
      responses:
        "200":
          description: Render list
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Render"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "429":
          $ref: "#/components/responses/RateLimited"
    post:
      tags: [Renders]
      summary: Create a render (synchronous)
      operationId: createRender
      description: |
        Accepts JSON with `image_url` or multipart form with an `image` file.
        Provide `instruction` (natural language), structured `options`, and/or `prompt`.
        Natural language is structured on the server into Studio-like options before generation.

        Successful creates charge **2 credits**. The response is the completed render
        (status `completed`) with `image_url`, or `failed` with an error (HTTP 500).
        Optional `idempotency_key` returns the prior row if the same key was used before.

        The HTTP response remains the primary delivery channel (synchronous). Active
        webhooks also receive a fire-and-forget signed POST; delivery failure does not
        change this response.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/CreateRenderJson"
            examples:
              landscape:
                value:
                  space_type: landscape
                  image_url: https://example.com/yard.jpg
                  instruction: Modern backyard with a linear pool, warm evening lighting, and tropical planting.
          multipart/form-data:
            schema:
              type: object
              required: [space_type, image]
              properties:
                space_type:
                  type: string
                  enum: [landscape, exterior, interior]
                image:
                  type: string
                  format: binary
                instruction:
                  type: string
                options:
                  type: string
                  description: JSON string of options
                prompt:
                  type: string
                realism:
                  type: number
                  minimum: 0
                  maximum: 100
                idempotency_key:
                  type: string
      responses:
        "201":
          description: Completed render (2 credits charged on success)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Render"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "402":
          $ref: "#/components/responses/PaymentRequired"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/ValidationError"
        "429":
          $ref: "#/components/responses/RateLimited"
        "500":
          description: Render job failed after accept
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Render"
  /renders/{id}:
    get:
      tags: [Renders]
      summary: Get a render by id
      operationId: getRender
      parameters:
        - in: path
          name: id
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Render
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Render"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
  /keys:
    get:
      tags: [Keys]
      summary: List API keys (session cookie auth)
      security: []
      operationId: listKeys
      description: Requires a signed-in Professional or Business browser session. Not for Bearer API keys.
      responses:
        "200":
          description: Keys (prefixes only)
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/ApiKeyMeta"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
    post:
      tags: [Keys]
      summary: Create API key (session cookie auth)
      security: []
      operationId: createKey
      description: Requires a signed-in Professional or Business browser session. Plaintext key returned once.
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
      responses:
        "201":
          description: Key created — plaintext returned once
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ApiKeyCreated"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
    delete:
      tags: [Keys]
      summary: Revoke API key (session cookie auth)
      security: []
      operationId: revokeKey
      parameters:
        - in: query
          name: id
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Revoked
          content:
            application/json:
              schema:
                type: object
                properties:
                  revoked:
                    type: boolean
                  id:
                    type: string
                    format: uuid
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /webhooks:
    get:
      tags: [Webhooks]
      summary: List completion webhooks (session cookie auth)
      security: []
      operationId: listWebhooks
      description: Requires a signed-in Professional or Business browser session.
      responses:
        "200":
          description: Webhook endpoints
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: "#/components/schemas/Webhook"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
    post:
      tags: [Webhooks]
      summary: Register completion webhook (session cookie auth)
      security: []
      operationId: createWebhook
      description: |
        HTTPS URLs only. Private, localhost, and cloud-metadata hosts are rejected.
        The signing secret (`whsec_…`) is returned once. Verify deliveries with
        `X-Renderspace-Signature: sha256=<hex>`, the HMAC-SHA256 of
        `<X-Renderspace-Timestamp>.<raw body>` with that secret. Max 5 webhooks per account.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [url]
              properties:
                url:
                  type: string
                  format: uri
                  example: https://example.com/hooks/renderspace
      responses:
        "201":
          description: Webhook created — signing secret returned once
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/WebhookCreated"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "422":
          $ref: "#/components/responses/ValidationError"
    patch:
      tags: [Webhooks]
      summary: Pause or resume a webhook (session cookie auth)
      security: []
      operationId: updateWebhook
      parameters:
        - in: query
          name: id
          required: true
          schema:
            type: string
            format: uuid
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required: [active]
              properties:
                active:
                  type: boolean
      responses:
        "200":
          description: Updated webhook
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Webhook"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/ValidationError"
    delete:
      tags: [Webhooks]
      summary: Delete webhook (session cookie auth)
      security: []
      operationId: deleteWebhook
      parameters:
        - in: query
          name: id
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Deleted
          content:
            application/json:
              schema:
                type: object
                properties:
                  deleted:
                    type: boolean
                  id:
                    type: string
                    format: uuid
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
  /webhooks/test:
    post:
      tags: [Webhooks]
      summary: Send a signed test delivery now (session cookie auth)
      security: []
      operationId: testWebhook
      description: |
        Sends one `webhook.test` event to the webhook and reports the receiver's answer.
        Limited to 60 per minute per account.
      parameters:
        - in: query
          name: id
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Delivery attempted
          content:
            application/json:
              schema:
                type: object
                properties:
                  delivered:
                    type: boolean
                  receiver_status:
                    type: [integer, "null"]
                  reason:
                    type: string
                    enum: [non_2xx, timeout, request_failed, host_not_public, invalid_url, signing_failed]
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/RateLimited"
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: rs_live_
      description: API key from Profile → API Keys (or POST /api/v1/keys while signed in).
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-API-Key
      description: Same value as the Bearer token (`rs_live_…`). Alternative to Authorization.
  schemas:
    Credits:
      type: object
      properties:
        plan_id:
          type: string
          enum: [professional, business]
        credits_remaining:
          type: [number, "null"]
        monthly_limit:
          type: [number, "null"]
        period_start:
          type: string
        near_limit:
          type: boolean
    CreateRenderJson:
      type: object
      required: [space_type, image_url]
      properties:
        space_type:
          type: string
          enum: [landscape, exterior, interior]
        image_url:
          type: string
          format: uri
        instruction:
          type: string
          description: Natural language design brief
        options:
          type: object
          additionalProperties: true
        prompt:
          type: string
          description: Optional full prompt override
        realism:
          type: number
          minimum: 0
          maximum: 100
        idempotency_key:
          type: string
    Render:
      type: object
      properties:
        id:
          type: string
          format: uuid
        status:
          type: string
          enum: [queued, running, completed, failed]
        space_type:
          type: string
          enum: [landscape, exterior, interior]
        image_url:
          type: [string, "null"]
          description: Result image URL when status is completed
        source_image_url:
          type: [string, "null"]
        instruction:
          type: [string, "null"]
        options:
          type: object
        credits:
          type: object
          properties:
            charged:
              type: [number, "null"]
              description: Credits charged for this render (2 on success)
        error:
          type: [string, "null"]
        created_at:
          type: string
          format: date-time
        completed_at:
          type: [string, "null"]
          format: date-time
    ApiKeyMeta:
      type: object
      properties:
        id:
          type: string
          format: uuid
        name:
          type: string
        key_prefix:
          type: string
        last_used_at:
          type: [string, "null"]
          format: date-time
        revoked_at:
          type: [string, "null"]
          format: date-time
        created_at:
          type: string
          format: date-time
    ApiKeyCreated:
      allOf:
        - $ref: "#/components/schemas/ApiKeyMeta"
        - type: object
          properties:
            api_key:
              type: string
              description: Full plaintext key — store immediately; not shown again
            warning:
              type: string
    Webhook:
      type: object
      properties:
        id:
          type: string
          format: uuid
        url:
          type: string
          format: uri
        active:
          type: boolean
        created_at:
          type: string
          format: date-time
    WebhookCreated:
      allOf:
        - $ref: "#/components/schemas/Webhook"
        - type: object
          properties:
            secret:
              type: string
              description: Signing secret (`whsec_…`) — store immediately; not shown again
            warning:
              type: string
    WebhookPayload:
      type: object
      description: JSON body POSTed to registered webhook URLs after a render finishes.
      properties:
        event:
          type: string
          enum: [render.completed, render.failed]
          description: "Test deliveries send a different body: event webhook.test with webhook_id, message and sent_at."
        id:
          type: string
          format: uuid
        status:
          type: string
          enum: [completed, failed]
        image_url:
          type: [string, "null"]
        credits:
          type: object
          properties:
            charged:
              type: [number, "null"]
        error:
          type: [string, "null"]
        created_at:
          type: string
          format: date-time
        completed_at:
          type: [string, "null"]
          format: date-time
    ApiError:
      type: object
      required: [error]
      properties:
        error:
          type: object
          required: [code, message]
          properties:
            code:
              type: string
            message:
              type: string
            details: {}
  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiError"
    Forbidden:
      description: Plan is not Professional or Business
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiError"
    PaymentRequired:
      description: Credits exhausted or subscription inactive (API renders cost 2 credits each)
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiError"
    RateLimited:
      description: Too many requests (60/min per key)
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiError"
    ValidationError:
      description: Invalid request
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiError"
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/ApiError"
