niyra_execute — long-running tasks

niyraexecute

The "do this for me" tool. Unlike niyraask, niyraexecute is allowed to invoke Niyra's full tool registry — email, calendar, web search, integrations, code execution, you name it.

When to use

- "Email Sarah and ask if next Tuesday at 3pm works for the kickoff."
- "Pull the Linear tickets tagged P0 and summarize them."
- "Research recent funding rounds in Series B vertical SaaS and draft a brief."

If the request is just "what is X" — that's niyraask.

Endpoint

| Method | Path | Auth | Scope |
| ------ | ---- | ---- | ----- |
| POST   | /v1/public/execute | Bearer token (PAT or OAuth) | niyra:execute |

MCP equivalent: POST /mcp with method tools/call, name niyraexecute.

Request

| Field | Type | Required | Notes |
| ----- | ---- | -------- | ----- |
| instruction | string | yes | What you want Niyra to do. Max 8000 chars. |
| conversationid | uuid | no | Pin to a thread for context continuity. |
| approvalmode | enum | no | auto (default — Niyra decides), dryrun (plan only, no side effects), confirm (return a plan; second call with confirmedtaskid to execute) |
| channelcontext | string | no | Where this request came from — colors Niyra's tone. |

Response — synchronous case

Returned when the work finishes inside the 60-second window:

Response — spawn-on-timeout case

When the work crosses 60 seconds, the same request returns:

Poll GET /v1/public/tasks/{taskid} until terminal: true. The task keeps running on Niyra's side regardless of whether you poll — losing the connection doesn't lose the work.

Code examples

curl

JavaScript with polling

Approval modes

| Mode | What happens |
| ---- | ------------ |
| auto | Niyra plans and executes in one shot. Default. |
| dryrun | Returns the plan Niyra would execute, with no side effects. Useful for previewing before committing. |
| confirm | Returns a plan with a pendingtaskid. Send a second execute call with confirmedtaskid:  to run it. |

Errors

| Status | Code | Meaning |
| ------ | ---- | ------- |
| 400 | invalidrequest | Empty instruction, too long, or invalid approvalmode |
| 401 | invalidtoken | Token revoked/expired/unknown |
| 403 | insufficientscope | Token lacks niyra:execute |
| 403 | tooldisabled | Niyra refused to run a tool the user has disabled in Settings → Skills |
| 429 | ratelimitexceeded | Per-token budget exhausted |

Related

- niyragettask — poll a spawned task
- niyra_ask — for "what is X" queries
- Scope catalog
- Rate limits