> ## Documentation Index
> Fetch the complete documentation index at: https://docs.melso.ai/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Melso product MCP: https://melso.ai/api/mcp (OAuth; one company per grant). REST: https://melso.ai. Documentation-search MCP: https://docs.melso.ai/mcp. The docs search server does not act on customer accounts.
>
> Use the live tool schema and respect company membership. Ask the person to authorize the exact fiscal document version in the signed-in app. A professional prepares and files included returns after authorization; AI does not file alone. A prepared file or approval receipt is not evidence of filing. Never claim completion from an accepted Task or Run. Keep credentials out of chat and logs. Agents features are internal or by private invitation.

# API quickstart

> Make a read-only API call in five minutes, then prepare funding before creating a Task.

<Info>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](/essentials/quickstart).</Info>

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](/mcp/connect) 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](/api-reference/authentication) 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](/api-reference/introduction#base-url):

```bash theme={null}
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](/api-reference/authentication#handle-tokens-securely).

## 2. Make your first read

```bash theme={null}
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:

```json theme={null}
{"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:

```bash theme={null}
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](/concepts/provider-accounts#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.

<Warning>
  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.
</Warning>

## 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](/api-reference/idempotency).

```bash theme={null}
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:

```json theme={null}
{
  "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:

```bash theme={null}
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](/api-reference/errors) and [Idempotency](/api-reference/idempotency) for other conflicts and retry rules.

## Follow the Task and read the answer

```bash theme={null}
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](/concepts/overview#run-status) to distinguish active work, a pause and a terminal attempt. A pending Task interaction is a question for its recipient. [Task events](/concepts/task-stream) and [webhooks](/api-reference/webhooks) can replace polling.

When the outcome Run is completed, read the newest assistant message whose `run_id` matches it:

```bash theme={null}
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](/concepts/messages-interactions).

## Next

When finished, run `unset MELSO_API_KEY` in this shell.

* [MCP setup](/mcp/connect): connect an assistant with explicit OAuth consent, then follow the [Claude](/mcp/claude) or [Cursor](/mcp/cursor) steps.
* [Tasks](/concepts/tasks-api): add context, isolation and execution options.
* [Execution funding](/concepts/provider-accounts): configure the key's own model funding.
* [WhatsApp tasks for Agents](/concepts/whatsapp-tasks): 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.

<CodeGroup>
  ```typescript TypeScript theme={null}
  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));
  }
  ```

  ```python Python theme={null}
  """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))
  ```
</CodeGroup>

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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.