---
title: "Submit a prompt for execution"
method: POST
path: "/api/v1/prompts"
tags: ["Prompts"]
---

# Submit a prompt for execution

`POST /api/v1/prompts`

## Request

- Base URL: `https://getorquesta.com`
- URL: `https://getorquesta.com/api/v1/prompts`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Queues a prompt on a project's agent. The prompt is created with status `pending`;
the agent picks it up on its next heartbeat (every 15 seconds) and transitions it to
`running` — there is no separate execute call. Poll `GET /api/v1/prompts/{id}` or
`GET /api/v1/logs?promptId=...` for progress.

Requires a token that can be attributed to a user: a CLI token (`oclt_`), or an org
API key (`oak_`) with the `prompts:write` scope. Agent tokens (`oat_`) are rejected —
a token that lives on the machine which would run the prompt cannot enqueue its own work.

A project you cannot reach returns 404, not 403, so ids cannot be probed.

## Request body

- object
  - `projectId` string, uuid, required
  - `content` string, required: The prompt text.
  - `context` object: Arbitrary JSON passed through to the agent.
  - `tags` string[]
  - `source` 'api' | 'dashboard'
  - `workstreamId` string, uuid: Run the prompt in this workstream: its agent (the microVM when the workstream runs there, which is woken), working directory and branch. 404 when the workstream is not in the project.

## Response `201`

Prompt created and queued.

- object
  - `prompt` object, required
    - `id` string, uuid
    - `projectId` string, uuid
    - `content` string
    - `status` string
    - `source` string
    - `createdBy` string, uuid
    - `createdAt` string, date-time
    - `workstreamId` string, uuid

## Other responses

- `400`: Invalid body, or the project has no agent configured.
- `401`: Missing or invalid API key.
- `403`: Insufficient scope, revoked token, or project-scope mismatch.
- `404`: Resource not found (or invisible to your scope).
- `500`: Internal server error.

---

[API](https://skmtc.dev/getorquesta/apis/orquesta-public-api.md) · [All operations](https://skmtc.dev/getorquesta/apis/orquesta-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/getorquesta/apis/orquesta-public-api/revisions/7d27e0ae8324?raw)