Cuiar API examples: Auth, tasks and webhooks

You’ll need the Cuiar app open and signed in, and app control through the API is Pro and Team.**

Your script needs a chore done behind a login: download an invoice, or search a booking site for a table. These Cuiar API examples each send one sentence for a chore in a signed-in account and show the result.

You’ll authenticate, run a full task with an approval, retry safely and verify a signed webhook.

Key Takeaways

• Work that your own Claude, Codex or other AI agent runs uses no Cuiar credits, because your AI plan pays for the model.
• CLI exit code 5 means the app is not open: open it, then run the command again.
• A routine with a webhook gets a POST signed with HMAC-SHA256, so your server can check the sender.

How do Cuiar API examples handle authentication?

You authenticate with the Cuiar API by sending a scoped API key as a Bearer token in the Authorization header of each request to https://api.cuiar.com. RFC 6750 defines this header form, with the example Authorization: Bearer mF_9.B5f-4.1JqM.

1. Create a scoped key. Run cuiar login, then use the keys commands to make a new key. The Cuiar CLI documentation lists the exact commands. Choose the smallest scope that fits the job from the list in the REST API reference.

Make one key for each script, so you can revoke it alone. 2. Store the key outside your code. Copy it once into an environment variable, and never paste it into a source file or a repository.

export CUIAR_API_KEY="paste-your-key-here"

3. Send the key as a Bearer token in the Authorization header, as in the next step.

4. Make a first call to POST /v1/tasks. Put the request fields that the OpenAPI 3.1 document in the reference names into task.json.

   curl -sS -i -X POST https://api.cuiar.com/v1/tasks \
     -H "Authorization: Bearer $CUIAR_API_KEY" \
     -H "Content-Type: application/json" \
     -d @task.json

A success shows a 2xx status line and a JSON body with the response fields that the reference lists. If the status line shows an authorization failure, check the key and its scope first.

What do you need before running Cuiar API examples?

The Cuiar docs say that the app must be open and signed in, because the REST API controls the Cuiar app.

The desktop app is not released yet. The download page lists each build as “Not yet released” and offers “E-mail me when it is ready”.

The CLI works today for key management, so you can create and store keys before the desktop app arrives.

What does a full Cuiar API task example look like?

A full Cuiar task example starts with one sentence, runs through POST /v1/tasks, and ends with a result after you answer one approval. Here the chore is to download a monthly invoice from a vendor portal.

1. Start the task. Put the prompt in task.json, using the fields the reference lists for POST /v1/tasks. The prompt is one sentence, as a user types it: “Download the September 2026 invoice from the vendor portal.”

curl https://api.cuiar.com/v1/tasks \
  -H "Authorization: Bearer $CUIAR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: invoice-2026-09" \
  --data @task.json

Reuse the same Idempotency-Key when you retry, so a retry does not start a second task.

2. Read the events. Call the events endpoint for the task from step 1, and read each event in order. The vault types the sign-in into the portal. The model gets only “signed in as” and the user name, so your script never handles a password.

3. Send a follow-up. The follow-up endpoint continues the task. Once the invoice has arrived, the follow-up can ask for the next chore: “E-mail the invoice to my accountant.”

4. Answer the approval. Sending an e-mail is an action that posts, sends, pays or changes an account, so the agent asks first.

The approval request appears in the events. Answer it with the call the reference describes. Don’t keep polling for a result while the task waits, because it’s stopped for your answer.

5. Handle the result. After you approve, the task finishes and returns the file or summary as the reference describes. Check that the invoice is for the right month before your script passes it on.

In a run, the task opens the portal in your own signed-in workspace, finds the September invoice and stops once, at the send step. The approval is the only decision your script makes.

How do you make the same Cuiar API call in cURL, TypeScript and the CLI?

In these Cuiar API examples, one task runs through all three clients. Each client returns the Lisbon table search result in its own form.

The task is the sentence “Search Lisbon, Friday 20:00, 4 people. Compare the tables under €40. Ask before it books.” The REST API reference and OpenAPI 3.1 document list the endpoints for tasks and routines. The cURL call sends the sentence to POST /v1/tasks.

curl -X POST https://api.cuiar.com/v1/tasks \
  -H "Authorization: Bearer $CUIAR_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d @task.json

Put the payload from the reference in task.json. For the TypeScript SDK, copy the package name, the import and the method calls from the SDK documentation on the same docs site, and pass the same sentence.

The Cuiar CLI takes the sentence as an argument:

cuiar exec --json "Search Lisbon, Friday 20:00, 4 people. Compare the tables under €40. Ask before it books." > result.json
echo $?

The CLI page sums up the contract as “One command, one result, one exit code.” Exit codes run from 0 to 9, and 5 means the Cuiar app is not open.

Add --workspace to pick the workspace, --permission to set the mode, and --incognito to keep no history.

The CLI works on macOS and Linux, and no Windows CLI is documented. Like the API, it needs the Cuiar app open and signed in to run a task.

All three clients get the same result: first the list of tables under €40, then a stop at the booking. The task waits there for your approval, because the agent asks before it books, as Cuiar’s security page states.

• cURL fits a quick test, a CI job, or a language the SDK does not cover.
• The TypeScript SDK fits a Node or web project that starts tasks and reads their results in code.
• cuiar exec --json fits a shell script or cron entry on macOS or Linux that needs one result and one exit code.

REST API, CLI or MCP: which way into Cuiar fits your script?

The three ways in reach the same Cuiar app, so choose by who runs the code and who holds the approval.

The remote MCP server at https://mcp.cuiar.com/mcp offers 22 tools and works on every plan.

The Cuiar MCP docs put the cost on your side: your own AI plan pays for the model.

The MCP tools are also reachable over /v1/rpc in the REST API. A service that can’t speak MCP can call the same tools with its API key.

• The REST API fits a service or webhook handler that starts tasks and answers approvals itself.
• The CLI fits a script on macOS or Linux that branches on an exit code.
• The remote MCP server fits Claude Code, Codex or Cursor, when you want your AI plan to pay and your client to approve.

Start free to get an e-mail when the desktop app is ready.

Which status codes, retries and exit codes do Cuiar API examples use?

The Cuiar API reports errors with standard HTTP status codes, accepts an Idempotency-Key header for safe retries, and the CLI returns exit codes 0 to 9 that a script can branch on.

For POST /v1/tasks, events, follow-ups, routines and /v1/rpc, each status class calls for one action:

RFC 9110 says that “The 401 (Unauthorized) status code indicates that the request has not been applied because it lacks valid authentication credentials for the target resource.” It also says that “The 403 (Forbidden) status code indicates that the server understood the request but refuses to fulfill it.”

How do you retry safely?

1. Make one key for each logical task. RFC 9110 states that “PUT, DELETE, and safe request methods are idempotent”, and POST is not on that list. The IETF draft says the Idempotency-Key header can make “non-idempotent HTTP methods such as POST or PATCH fault-tolerant”.

Cuiar’s developer docs list Idempotency-Key among the REST API features. 2. Send the same key on every retry of that task, and give a new task a new key. 3. Back off on 429. RFC 6585 says that “The 429 status code indicates the user has sent too many requests in a given amount of time ("rate limiting").”

If the response has a Retry-After header, wait that long. RFC 9110 says it “indicates how long the user agent ought to wait before making a follow-up request”. Read the current rate limits in the REST API reference, and do not hard-code them.

KEY=$(uuidgen)
curl -sS https://api.cuiar.com/v1/tasks \
  -H "Authorization: Bearer $CUIAR_API_KEY" \
  -H "Idempotency-Key: $KEY" \
  -H "Content-Type: application/json" \
  -d @task.json

4. Branch on the CLI exit code. In the loop, code 0 ends the retries, code 5 waits 30 seconds for the app, and any other code stops the script. The Cuiar CLI page lists the other codes.

for attempt in 1 2 3; do
  cuiar exec --json "Download last month's invoice from the vendor portal" > result.json
  code=$?
  case $code in
    0) break ;;
    5) echo "The Cuiar app is not open. Open it and sign in." >&2; sleep 30 ;;
    *) echo "cuiar exited with code $code" >&2; exit "$code" ;;
  esac
done

A task from the API waits at any action that pays, posts, sends or changes an account. A wait for your approval is not an error, so do not retry it.

How do you verify a Cuiar webhook and keep your keys safe?

RFC 2104 defines HMAC. The Cuiar developer docs cover signed webhooks next to the REST API for tasks and routines.

1. Read the webhook section of the docs first. It states the header that carries the signature, the exact bytes that are signed and the payload fields of a routine event. Use those names as written.
2. Keep the raw request body. Verify the signature before you parse the JSON, because a parser can change the bytes. Compute the HMAC over the body exactly as it arrived.
3. Compare in constant time. A plain === stops at the first wrong byte and leaks timing.

import { createHmac, timingSafeEqual } from "node:crypto";

export function isValid(rawBody: Buffer, received: Buffer, secret: string): boolean {
  const expected = createHmac("sha256", secret).update(rawBody).digest();
  return received.length === expected.length && timingSafeEqual(received, expected);
}

4. Reject a bad signature before any work. Return a 401 and do nothing else. Decode the header value into bytes with the encoding the docs state, then pass it as received.

When a routine finishes, your endpoint gets the POST, isValid returns true, and your code reads the payload. A forged request returns false and ends at the 401.

Which controls keep your keys safe?

The OWASP API Security Top 10 2023 lists “API1:2023 - Broken Object Level Authorization” and “API5:2023 - Broken Function Level Authorization”. Four controls answer them.

• Scope each key. Give each script one key with the least scope it needs, so a leaked key reaches only that job.
• Revoke one key at a time. When a script is retired or a key leaks, revoke that key and leave the others running.
• Pick the permission mode per job. Use read-only for reports, and keep guard mode for anything that changes an account.
• Verify every webhook. Run the HMAC check on each POST, and keep the signing secret out of your repository.

Cuiar’s security page explains “why page text never gives it orders”, so a hostile page cannot rewrite your task.

Frequently asked questions

What are Cuiar API examples?

They are calls to https://api.cuiar.com that each do one chore in a signed-in account, with a scoped API key sent as a Bearer token. Each one starts a task with POST /v1/tasks, reads its events, sends a follow-up and handles the result.

Does the Cuiar API work on the Free plan?

Cuiar pricing says app control with an API key needs Pro or Team. The remote MCP server for your own AI agent runs on every plan, including Free, at https://mcp.cuiar.com/mcp.

Does the Cuiar API need the app open?

Yes. The Cuiar app must be open and signed in, because the API controls the app. The desktop app is not released yet. Make an account at cuiar.com/signup, and Cuiar sends an e-mail when the build is ready.

Do API tasks use credits when my own Claude or Codex drives them?

Tasks that your own AI agent runs use no Cuiar credits, because your AI plan pays for the model. The run_task tool is different: Cuiar’s built-in model does that work, and it uses credits.

What should you do next with these Cuiar API examples?

Start these Cuiar API examples with the CLI, because none of the first steps needs the desktop app.

Today, install the CLI with its one-line command from the developer docs, run cuiar login, and create one scoped key. Then read the OpenAPI document on the same site.

This week:

• Run one read-only task and read its events.
• Run one guard-mode task and answer its approval.
• Add an Idempotency-Key to every POST.

Next, add a routine with a signed webhook, and verify the signature before your code trusts the POST.

Tasks need the app open and signed in, and the desktop builds are not released yet. You can run the CLI steps today and decide on a plan later.

Sources

Cuiar documentation · Cuiar MCP server: one URL for any MCP client · Cuiar CLI for AI agents and scripts · RFC 6750: The OAuth 2.0 Authorization Framework: Bearer… · Download Cuiar for macOS, Windows and Linux · Security at Cuiar: the agent, the browser and our servers · RFC 9110: HTTP Semantics · Cuiar pricing. Every other source is linked where the article cites it.