> ## Documentation Index > Fetch the complete documentation index at: https://docs.warmr.so/llms.txt > Use this file to discover all available pages before exploring further. # Enqueue a run (warm_up or post). ## OpenAPI ````yaml /api/openapi.yaml post /v1/runs openapi: 3.1.0 info: title: Warmr Cloud API version: '1.2' summary: Enqueue and read iPhone-fleet automation work (warmups + posts). description: > The business-facing REST surface for Warmr. **Bring-your-own-fleet**: API keys *enqueue* work and read org-scoped state; your own connected iPhones *execute* it. A server-side **airlock** prevents an API session from ever driving a device. Auth is a two-step flow: exchange a `wk_live_` API key at the exchange endpoint for a short-lived org session, then call `/v1` with `Authorization: Bearer `. Every `/v1` response is wrapped in an envelope `{ "schema": "1.0", ... }`; errors are `{ "schema": "1.0", "error": { "code", "message", "data"? } }`. The exchange endpoint uses a flatter `{ "error": "" }` body. NOTE: the public base URL is deployment-specific and is NOT asserted here. Replace the `app.warmr.so` / `` placeholders below with your deployment's values. license: name: UNLICENSED servers: - url: https://{origin} description: Substitute your Warmr deployment origin. app.warmr.so is a placeholder. variables: origin: default: app.warmr.so description: Your Warmr deployment host, no scheme, e.g. app.example.com security: - bearerAuth: [] tags: - name: auth description: Exchange an API key for an org session. - name: runs description: >- Enqueue and read units of automation work (warm_up or post); your connected iPhones execute them. - name: schedules description: >- Standing recurring post schedules (one account each). The materializer turns them into runs. - name: accounts description: Register and list the social account handles in your org. - name: content description: >- Signed direct-to-storage uploads for post clips (issue → upload → confirm). - name: usage description: Org storage and run counts for a billing period. - name: devices description: The iPhones your runner(s) have reported to the org. - name: webhooks description: >- Subscribe to run.completed / run.failed events and manage deliveries. Opt-in, secret-bearing (webhooks:read / webhooks:write). - name: keys description: >- List your org's API keys — metadata only, the secret is never returned. Opt-in keys:read. - name: health description: Lightweight org-scoped readiness probe. Opt-in health:read. paths: /v1/runs: post: tags: - runs summary: Enqueue a run (warm_up or post). operationId: createRun parameters: - $ref: '#/components/parameters/IdempotencyKey' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CreateRunRequest' responses: '200': description: >- Idempotent replay — the original run for a duplicate Idempotency-Key. headers: RateLimit-Limit: $ref: '#/components/headers/RateLimit-Limit' RateLimit-Remaining: $ref: '#/components/headers/RateLimit-Remaining' RateLimit-Reset: $ref: '#/components/headers/RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/RunEnvelope' '202': description: Run enqueued. headers: RateLimit-Limit: $ref: '#/components/headers/RateLimit-Limit' RateLimit-Remaining: $ref: '#/components/headers/RateLimit-Remaining' RateLimit-Reset: $ref: '#/components/headers/RateLimit-Reset' content: application/json: schema: $ref: '#/components/schemas/RunEnvelope' '400': $ref: '#/components/responses/Error' '401': $ref: '#/components/responses/Error' '403': $ref: '#/components/responses/Error' '413': $ref: '#/components/responses/Error' '422': $ref: '#/components/responses/Error' '429': $ref: '#/components/responses/Error' components: parameters: IdempotencyKey: name: Idempotency-Key in: header required: false description: Dedupes a `post` run; a duplicate key returns the original run (200). schema: type: string schemas: CreateRunRequest: type: object required: - type - account_username properties: type: type: string enum: - warm_up - post account_username: type: string minLength: 1 device_udid: type: string input: $ref: '#/components/schemas/CreateRunInput' scheduled_at: type: string format: date-time RunEnvelope: allOf: - $ref: '#/components/schemas/Envelope' - type: object required: - run properties: run: $ref: '#/components/schemas/Run' CreateRunInput: type: object properties: upload_id: type: string description: Required for a post. disposition: type: string default: post_now caption: type: string Envelope: type: object required: - schema properties: schema: type: string const: '1.0' Run: type: object required: - run_id - status - type properties: run_id: type: string status: $ref: '#/components/schemas/RunStatus' type: type: string description: job_type (e.g. warm_up, post). account_username: type: - string - 'null' device_udid: type: - string - 'null' upload_id: type: - string - 'null' description: drop_upload_id (set for posts). disposition: type: - string - 'null' scheduled_at: type: - string - 'null' format: date-time created_at: type: - string - 'null' format: date-time updated_at: type: - string - 'null' format: date-time error: type: - string - 'null' description: error_message, or null. ErrorEnvelope: allOf: - $ref: '#/components/schemas/Envelope' - type: object required: - error properties: error: type: object required: - code - message properties: code: type: string message: type: string data: {} RunStatus: type: string description: Public run lifecycle. Forward-compatible (unknown values may appear). enum: - queued - claimed - running - succeeded - failed - canceled headers: RateLimit-Limit: description: >- Per-org enqueue cap for the fixed window (advisory; draft RFC 9331 style). schema: type: integer RateLimit-Remaining: description: >- Approximate enqueues left in the current window at check time (clamped to >= 0). schema: type: integer RateLimit-Reset: description: Seconds until the enqueue window resets. schema: type: integer responses: Error: description: A /v1 error envelope. content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: The access_token from the exchange endpoint. ````