Skip to main content

How do I make my first API request, and why do I get "tool-not-accessible"?

Send your first Run request with curl, find the exact owner/model path for any model, and fix "tool-not-accessible" ("tool not available") and other run errors.

Every model on Wiro can be run through the same endpoint: a POST request to https://api.wiro.ai/v1/Run/{owner}/{model}. The request starts a task and answers right away with a task ID, and you then check that task for the result. If your API key is accepted but every call returns tool-not-accessible (often reported as "tool not available"), the {owner}/{model} part of the URL is usually the cause. If the message is This model is not available for your team instead, the path is right and a team setting is blocking the model (see below).

Start here: the Quick Start and Run endpoint pages of our docs show this request in curl, Python, Node.js, PHP and more. Their examples use {owner-slug}/{model-slug} as a placeholder, so replace it with a real path such as claude/fable-5.

Your first request

You need an API key from a Wiro project (see How do I get an API key?). This example uses API Key Only authentication, which sends just the x-api-key header, so it works only with a project whose auth method is API Key Only (Simple). The New Project form preselects Signature Based (Recommended), and with a key from such a project this call fails with HTTP 401 (Project requires signature authentication...). Your Projects page shows each project's auth method.

The example runs claude/fable-5, a text model whose only required input is prompt:

curl -X POST "https://api.wiro.ai/v1/Run/claude/fable-5" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"prompt": "Hello, world!"}'

Replace YOUR_API_KEY with your key. Your account needs a balance of at least $0.50 (for a team project, the team's balance), or the run returns Insufficient balance. On Windows, run the command in Git Bash or WSL, or use the Python or Node.js version from the docs.

A successful call returns "result": true with a taskid and a socketaccesstoken, for example:

{
  "result": true,
  "errors": [],
  "taskid": "2221",
  "socketaccesstoken": "eDcCm5yyUfIvMFspTwww49OUfgXkQt"
}

Signature Based projects also send x-nonce (a Unix timestamp or random integer) and x-signature (the HMAC-SHA256 of your API secret plus the nonce, keyed with your API key, as a hex string). See Authentication.

Find the Run URL for any model

  1. Open the model in the model catalog.

  2. Put the two parts after /models/ in the page address after /v1/Run/. For example, https://wiro.ai/models/claude/fable-5 becomes https://api.wiro.ai/v1/Run/claude/fable-5. If the address ends with ?something=value, leave that out of the URL and send it as an input in the request body instead ("something": "value").

  3. For ready-made code, open the model page's API Integration Guide tab (or click View full API docs under API quick start). If you're signed in and choose your project under Select your project, the code includes your real API key and matches your project's authentication method, so don't paste it into chats, screenshots or public repositories.

  • Letter case in the owner and model names doesn't matter, and the other spelling some API quick start boxes show also works. For example, the openai/gpt-5-2 page shows openai/gpt-5.2, and both reach the same model.

  • If the name in that box contains a space (for example wiro/Virtual Try-On), use the version from the page address instead (wiro/virtual-try-on). curl rejects a URL with a raw space.

  • The quick start's example body contains placeholder values such as "..." and https://your-cdn.com/input.png. Replace them with real values, or leave out the optional ones.

  • Send the request to api.wiro.ai, not to the wiro.ai page address, and write /v1/Run/ with a capital R.

To check a path before you run anything, open its model page: if https://wiro.ai/models/{owner}/{model} doesn't open, that path won't work in the API either. You can also ask the API for the model's details:

curl -X POST "https://api.wiro.ai/v1/Tool/Detail" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"slugowner": "claude", "slugproject": "fable-5"}'

If it returns "result": true, the path is right. tool[0].parameters lists the model's inputs in groups: in each group's items, id is the input name and "required": true marks the ones you must send. If it returns tool-not-accessible, the owner or model name is wrong, or the model isn't public.

Why do I get "tool-not-accessible"?

It means your API key was accepted, but the API couldn't match the {owner}/{model} in your URL to a model you can run. The key is checked first, and a bad key fails with HTTP 401 and a different message. This error comes back with HTTP 200, "result": false and the message tool-not-accessible. Common causes:

  • Placeholders left in the URL. The docs examples use {owner-slug}/{model-slug}. Left in the URL, they point to a model that doesn't exist. curl even drops the braces silently and asks for owner-slug/model-slug, so the URL can look almost right. Replace them with a real path such as claude/fable-5.

  • A wrong owner or model name. A typo, a model's display title, or a name copied from an example that isn't in the catalog. Copy the path from the model page address.

  • The model isn't public. It exists but isn't published for API use (the error then has "code": 1 instead of 0). Pick a model from the catalog.

Letter case in the owner or model is never the cause: Claude/Fable-5 finds the same model as claude/fable-5.

"This model is not available for your team" is a separate error. The path is right, but your API key belongs to a team project and a team admin has limited which models the team can run. Ask your team admin to allow the model.

Other errors you might see

  • Project authorization is not founded. (HTTP 401): the API key is wrong. Copy it again from your project.

  • Authorization bearer token is not founded in headers. (HTTP 401): no x-api-key header arrived, so check its name. You also get this if you open the Run URL in a browser.

  • Authorization bearer token is invalid. (HTTP 401): you sent an Authorization header, for example Authorization: Bearer YOUR_API_KEY. The Run API ignores x-api-key whenever Authorization is present, so remove it and send only x-api-key. Bearer keys are for the LLM Gateway.

  • Project requires signature authentication. x-signature and x-nonce headers are required. (HTTP 401): your project uses Signature Based auth. Add those headers, or use a project with API Key Only.

  • Project authorization is not valid. (HTTP 401): the signature doesn't match.

  • Requested ip ... is not allowed. (HTTP 401): your project's IP Whitelist doesn't include the address you're calling from. Add it, or clear the whitelist to accept any IP address, in the project settings. Changing the whitelist generates a new API Secret.

  • Parsing url error. (HTTP 404): the path isn't a Wiro endpoint, for example /v1/run/ in lowercase.

  • Cannot GET /v1/Run/... (HTTP 404): the request was sent as GET. Send it as POST (curl -X POST).

  • Parsing request error. (HTTP 400, plain text): the JSON body is malformed. Check the quotes and braces.

  • Request parameter [prompt] required: a required input is missing, or the Content-Type: application/json header is missing, so the body wasn't read as JSON. Check the model's inputs with Tool/Detail.

  • Insufficient balance (code 97): add funds. A run needs a balance of at least $0.50 ($10 for training models).

  • You have reached your concurrent task limit (code 96): see How many tasks can I run at the same time?

After a successful run: check the task

Send the socketaccesstoken from the run response as tasktoken (or send "taskid" instead):

curl -X POST "https://api.wiro.ai/v1/Task/Detail" \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{"tasktoken": "YOUR_SOCKETACCESSTOKEN"}'

  • Repeat every few seconds until tasklist[0].status is task_postprocess_end (finished) or task_cancel (cancelled). task_error is not final, so keep waiting.

  • Then check pexit: "0" means success. The result is in outputs (file URLs for image, video and audio models). For text models, the reply is also in debugoutput.

  • Failed runs (pexit other than "0") are not billed, and their totalcost is "0". Realtime models that are charged per conversation turn are the exception.

  • Instead of polling, you can follow the task over a WebSocket, or add a callbackUrl to the run request and Wiro will POST the result to it when the task completes. See the Task Detail section of Tasks for the full response.

Good to know

  • Errors from the Run step itself (model lookup, inputs, balance, team) come back with HTTP 200 and "result": false, so check result and errors, not only the status code. Authentication, URL and JSON-format errors use HTTP 401, 404 and 400.

  • To get the result in the same call, add /sync to the Run URL, for example https://api.wiro.ai/v1/Run/claude/fable-5/sync. It waits up to 40 minutes and returns the finished task. If the wait times out, you get HTTP 504 with the taskid and socketaccesstoken. The task keeps running and is billed as usual, so continue with Task/Detail. Training and realtime models aren't supported there (The synchronous wrapper is not available for this model.); use the normal Run URL for them.

  • Models that take files (images, audio, documents) also accept a public file URL in the JSON body, for example inputImageUrl for an inputImage input. To upload the file itself, use multipart/form-data. See JSON vs Multipart in Model Parameters.

  • With API Key Only, the key alone authorizes requests, so keep it on your own server and never put it in browser or mobile app code.

Related Articles
Did this answer your question?