API quickstart

Melso Agents is available only internally or by private invitation. Agents-specific features require existing access. For the autónomo fiscal service, see Get started.

The five-minute goal is a successful read-only API call using existing invited Agents access and a company key. It starts no Run and needs no execution funding. If you use Melso for fiscal work, follow MCP setup for a first read from your assistant.

1. Get a company key

An owner or admin of an Agents company can create a key in Settings → API keys. Save it when it is shown; it is returned once. Creating a key in another company type returns 403 with code: agents_only. The authentication guide describes supported personal tokens and credential scopes. A company key already identifies its company. Omit the company header. In Bash, enter the key at the hidden prompt so it stays out of terminal history. MELSO_URL follows the base URL convention:

export MELSO_URL='https://melso.ai'
read -r -s -p 'Company API key: ' MELSO_API_KEY
printf '\n'
export MELSO_API_KEY

Keep shell tracing off. Use a secret manager for services, and keep credentials out of source control and logs. Environment variables can be read by child processes; see token handling.

2. Make your first read

curl --fail-with-body "$MELSO_URL/api/tasks?limit=1&offset=0" \
  -H "Authorization: Bearer $MELSO_API_KEY"

For an account with no open Tasks, the response is:

{"tasks": [], "total": 0}

An HTTP 200 with this list envelope is your first success. Existing Tasks appear in tasks. To check the integration identity and its company, call GET /api/me with the same Bearer header. You can stop here; the remaining steps start work.

Before creating a Run: confirm funding

A company key uses its own integration identity’s funding policy; it cannot borrow a member’s subscription account. Read that policy before requesting execution:

curl --fail-with-body "$MELSO_URL/api/provider-accounts/harnesses" \
  -H "Authorization: Bearer $MELSO_API_KEY"

For the codex harness used below, check next_method and next_reason. Configure permitted Melso credits or a provider API key through Harness access and BYOK; an ordinary key identity must keep accounts_enabled: false. Cloud execution also needs usable company compute funding. Confirm it in Billing before proceeding.

Starting a Run uses execution capacity and can incur usage charges. If the requested funding is unavailable, creation returns 409 with error: requested execution funding is unavailable. Resolve the policy, credit or capacity issue before creating work; a successful read does not establish execution readiness.

Create a Task and start work

input is the first message. execution requests a Run. In an Agents company, omitting execution saves the Task without running it. Send a fresh UUID as client_request_id; keep the same ID and body if you need to retry an uncertain response. An identical replay also returns 201, with the existing Task and original run_id; it does not create another Task or Run. See Idempotency.

export REQUEST_ID="$(python3 -c 'import uuid; print(uuid.uuid4())')"
curl --fail-with-body "$MELSO_URL/api/tasks" \
  -H "Authorization: Bearer $MELSO_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"client_request_id\":\"$REQUEST_ID\",\"input\":\"Say hello.\",\"execution\":{\"harness\":\"codex\"}}"

The 201 response contains the Task and, when a Run started, its run_id. This excerpt shows the identifiers to retain:

{
  "id": "11111111-1111-4111-8111-111111111111",
  "run_id": "22222222-2222-4222-8222-222222222222"
}

Set TASK_ID to the actual id from your response, not the example value:

export TASK_ID='TASK_UUID_FROM_CREATE_RESPONSE'

A 401 means credentials need attention; 403 workspace_key_scope means the key cannot access that route or company. See Errors and Idempotency for other conflicts and retry rules.

Follow the Task and read the answer

curl --fail-with-body "$MELSO_URL/api/tasks/$TASK_ID/runs" \
  -H "Authorization: Bearer $MELSO_API_KEY"

Follow successor Runs after retries and pauses. Use the complete Run status table to distinguish active work, a pause and a terminal attempt. A pending Task interaction is a question for its recipient. Task events and webhooks can replace polling. When the outcome Run is completed, read the newest assistant message whose run_id matches it:

curl --fail-with-body "$MELSO_URL/api/tasks/$TASK_ID/messages/page" \
  -H "Authorization: Bearer $MELSO_API_KEY"

Use the stored message for the reply; it has output redaction applied. A delivered result needs review and does not close the Task. Continue with POST /api/tasks/{id}/input and a new client_request_id; see Messages and interactions.

When finished, run unset MELSO_API_KEY in this shell.

MCP setup: connect an assistant with explicit OAuth consent, then follow the Claude or Cursor steps.
Tasks: add context, isolation and execution options.
Execution funding: configure the key’s own model funding.
WhatsApp tasks for Agents: request work from your linked chat.

Read Tasks in TypeScript or Python

Load MELSO_API_KEY with the hidden prompt above or your secret manager. These examples perform a read and fail clearly on an HTTP error. They use the language’s standard HTTP support and require Node.js 22 LTS or Python 3.10 or later.

import { pathToFileURL } from 'node:url';

type Task = { id: string; identifier: string; title: string; status: string };
export async function listTasks(token: string, baseUrl = 'https://melso.ai'): Promise<{ tasks: Task[]; total: number }> {
  const response = await fetch(`${baseUrl}/api/tasks?limit=20&offset=0`, {
    headers: { Authorization: `Bearer ${token}`, Accept: 'application/json' },
    signal: AbortSignal.timeout(30_000),
  });
  if (!response.ok) throw new Error(`Melso returned HTTP ${response.status}: ${await response.text()}`);
  return await response.json() as { tasks: Task[]; total: number };
}
if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
  const token = process.env.MELSO_API_KEY;
  if (!token) throw new Error('Set MELSO_API_KEY to your company API key.');
  console.log(JSON.stringify(await listTasks(token, process.env.MELSO_URL), null, 2));
}

"""Read Tasks using a company key. No writes are performed."""
import json,os
from urllib.error import HTTPError
from urllib.request import Request,urlopen

def list_tasks(token:str,base_url:str='https://melso.ai')->dict:
    request=Request(base_url+'/api/tasks?limit=20&offset=0',headers={'Authorization':'Bearer '+token,'Accept':'application/json'})
    try:
        with urlopen(request,timeout=30) as response:return json.load(response)
    except HTTPError as error:
        with error:
            detail=error.read().decode()
        raise RuntimeError(f'Melso returned HTTP {error.code}: {detail}') from error

if __name__=='__main__':
    print(json.dumps(list_tasks(os.environ['MELSO_API_KEY'],os.environ.get('MELSO_URL','https://melso.ai')),indent=2))

Save the Python snippet as tasks.py and run python3 tasks.py. For TypeScript, use your project’s TypeScript runner or compile it for Node.js. Use a valid company key and an account with access to Tasks. These snippets do not start a Run.

Get started

Conventions

Endpoints

API quickstart

1. Get a company key

2. Make your first read

Before creating a Run: confirm funding

Create a Task and start work

Follow the Task and read the answer

Next

Read Tasks in TypeScript or Python

​1. Get a company key

​2. Make your first read

​Before creating a Run: confirm funding

​Create a Task and start work

​Follow the Task and read the answer

​Next

​Read Tasks in TypeScript or Python

1. Get a company key

2. Make your first read

Before creating a Run: confirm funding

Create a Task and start work

Follow the Task and read the answer

Next

Read Tasks in TypeScript or Python