Calling a tool

Request

POST https://api.crab.talk/services/{owner}/{name}/tools/{tool}
Authorization: Bearer ck_…
Content-Type: application/json

{"query": "hello"}

• {owner} is the account's handle or id.
• The body is the tool's arguments as a JSON object.
• The token is an API key or a session. A call needs no scope.

Response

A tool that ran answers 200, whether it succeeded or failed:

{"done": "{\"query\":\"hello\"}"}

{"failed": "query is empty"}

• done holds the tool's result as JSON text, which is parsed a second time.
• Berm-Meter says what the call used.
• A deprecated tool's answer carries Deprecation, and Sunset once one is set.

Query tools

A #[query] tool only reads, and is also called with GET:

GET https://api.crab.talk/services/{owner}/{name}/tools/{tool}?args=%7B%22id%22%3A42%7D

• args is the arguments as URL-encoded JSON.
• The answer carries an ETag. A request sending it back in If-None-Match answers 304 while the service's data is unchanged, without running the tool.
• GET on a tool that is not a query answers 405.

Errors

An error answers {"error": "…"}.

Status	When
401	No token, or a token that is not valid.
402	The service's account is past its plan. See Plans.
403	The tool takes calls only from other services, or an app refused the call.
404	No such service, a private service the caller cannot see, or no public tool of that name.
405	GET on a tool that is not a query.
429	Past the rate limit, or the service's account has as many calls running as its plan allows. See Plans.
502	The service did not answer.
503	The service is unavailable, or every call slot on the node running it is taken.

Rate limits

• 600 calls a minute per account, and per signed-in user of an app.
• 60 calls a minute per client address, for an app's anonymous calls.

Reading a service

Route	Answers
GET /services/{owner}/{name}	Its public tools, their arguments and descriptions, its README, and the calls it served each day.
GET /services/{owner}/{name}/idl	Its interface alone.
GET /services/{owner}/{name}/terms	Each public tool's budget.
GET /users/{user}/services, GET /orgs/{org}/services	An account's services.

These take a token or none. A private service answers only its own account's members and keys.