Melso Docs

Quickstart

Create a Task, follow its Runs and read the answer.

Create a workspace API key in Settings → API keys. The dialog shows the key once, ready to paste. The key is all you need: it belongs to one workspace and implies it, so don't send X-Workspace-ID with it; one naming another workspace returns 403 with "code":"workspace_key_scope". A personal access token also works but needs X-Workspace-ID, because a person can belong to several workspaces; see Overview and authentication for credential types.

export MELSO_API_KEY='mwk_…'

GET /api/me answers with the key's identity and the workspace it belongs to:

curl https://melso.ai/api/me \
  -H "Authorization: Bearer $MELSO_API_KEY"

Create a Task

input is the first message. execution starts a Run right away with the harness you choose; without it, the Task is saved and does not run.

curl https://melso.ai/api/tasks \
  -H "Authorization: Bearer $MELSO_API_KEY" \
  -d '{
    "input": "Say hello and tell me what you can do.",
    "execution": { "harness": "codex" }
  }'

The response is the Task. Store its id: it identifies the conversation for follow-ups. run_id is the Run this request started. To retry after an uncertain response, send a UUID client_request_id and repeat the same body; see Idempotency.

Follow the Task's Runs

The Run you started is not always the one that finishes: automatic retries, Cloud lifetime rollovers and pauses add successor Runs, and the first Run can end as failed or cancelled while its successor carries on. Poll the Task's Runs, newest first, with TASK_ID set to the Task's id:

curl https://melso.ai/api/tasks/$TASK_ID/runs \
  -H "Authorization: Bearer $MELSO_API_KEY"

Keep waiting while any Run is queued, dispatched, running or deferred. Then the newest Run is the outcome: completed delivered a reply, failed or cancelled stopped (error and failure_reason, when set, say why), and paused waits for POST /api/tasks/{id}/resume. An entry with status pending in GET /api/tasks/{id}/interactions is a question for you. Webhooks can notify you instead of polling; over MCP, tasks_wait holds each call for up to 20 seconds.

Read the answer

The reply is the newest message with role assistant whose run_id is the completed Run's id. The first page of /messages/page holds the newest messages:

curl https://melso.ai/api/tasks/$TASK_ID/messages/page \
  -H "Authorization: Bearer $MELSO_API_KEY"

Read the reply from the message rather than the Run's result.output: the stored message has secret-looking values redacted, and a reply that arrived double-escaped, with \n escapes instead of real line breaks, is decoded. Any single-line reply containing \n or \r, such as the path C:\new\folder, is decoded too.

A delivered answer is ready for review; it does not close the Task. To continue, POST /api/tasks/{id}/input with {"content":"…"} queues the next Run in the same Task and sandbox. Add a UUID client_request_id and repeat the same body to retry after an uncertain response without sending the input twice. See Messages and interactions.

Next

On this page

Create a TaskFollow the Task's RunsRead the answerNext