toolaby-app Uses API
The Uses API from toolaby-app — 1 operation(s) for uses.
The Uses API from toolaby-app — 1 operation(s) for uses.
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/toolaby-app:toolaby-app-uses-api"
curl "https://apis.io/api/v1/apis?limit=25"
Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Toolaby Uses API
version: '2026-09-16'
description: 'Look up whether a person holds a tool, and grant or revoke access. Keys are created under Configure → API and sent as a bearer token. Errors are `{ error: { type, message, param? } }`.'
servers:
- url: /
security:
- bearer: []
tags:
- name: Uses
paths:
/api/v1/tools/{slug}/uses:
get:
tags:
- Uses
summary: Retrieve a buyer's uses
description: 'What the buyer the site token names holds of the tool, and how many of its free uses are left, counting nothing: for your page to say before the first use.'
parameters:
- schema:
type: string
pattern: ^[a-z0-9][a-z0-9-]{1,118}$
example: invoice-grabber
description: 'The tool id: the full one (acme--invoice-grabber) or the short one the dashboard shows (invoice-grabber).'
required: true
description: 'The tool id: the full one (acme--invoice-grabber) or the short one the dashboard shows (invoice-grabber).'
name: slug
in: path
- schema:
type: string
pattern: ^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$
description: 'The buyer''s site token: `Toolaby.token({ tool })` on your page, or `toolaby.siteToken({ audience })` in your extension. It lasts five minutes and names the buyer, the tool and the page.'
example: eyJhbGciOiJFUzI1NiIs…
required: true
description: 'The buyer''s site token: `Toolaby.token({ tool })` on your page, or `toolaby.siteToken({ audience })` in your extension. It lasts five minutes and names the buyer, the tool and the page.'
name: toolaby-site-token
in: header
responses:
'200':
description: The buyer's uses.
content:
application/json:
schema:
$ref: '#/components/schemas/Usage'
'400':
description: A parameter is missing or wrong; `param` names it.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: No key, a malformed or revoked one; or a site token that is not valid for this tool, or has ended.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: 'The workspace''s plan does not allow it: on Hobby, 100 passes at once.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: No such tool, grant or person in this workspace.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: A request with this Idempotency-Key is still being answered.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: More than a minute's requests from this key, its workspace's or its owner's; the buyer's minute of asks; or the buyer's day of free uses.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Toolaby's fault, or it cannot count the workspace's additions just now. Retry.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'503':
description: Toolaby cannot read or count the buyer's uses just now. Retry.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
operationId: getApiV1ToolsBySlugUses
x-operation-id-source: derived
post:
tags:
- Uses
summary: Count a buyer's uses
description: 'Counts `count` of the buyer''s uses of the tool, for an action your server does for them: allowed and counted, or refused whole with why (`reason`) and what remains. A buyer who holds the tool, or a tool open to everyone, counts nothing. Send an `Idempotency-Key` made from what the action counts: a retry with the same key and count answers what the first did and counts nothing more, for 24 hours; the same key with another count is refused. A refusal counts nothing and is not kept.'
parameters:
- schema:
type: string
pattern: ^[a-z0-9][a-z0-9-]{1,118}$
example: invoice-grabber
description: 'The tool id: the full one (acme--invoice-grabber) or the short one the dashboard shows (invoice-grabber).'
required: true
description: 'The tool id: the full one (acme--invoice-grabber) or the short one the dashboard shows (invoice-grabber).'
name: slug
in: path
- schema:
type: string
pattern: ^[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+$
description: 'The buyer''s site token: `Toolaby.token({ tool })` on your page, or `toolaby.siteToken({ audience })` in your extension. It lasts five minutes and names the buyer, the tool and the page.'
example: eyJhbGciOiJFUzI1NiIs…
required: true
description: 'The buyer''s site token: `Toolaby.token({ tool })` on your page, or `toolaby.siteToken({ audience })` in your extension. It lasts five minutes and names the buyer, the tool and the page.'
name: toolaby-site-token
in: header
- schema:
type: string
description: Optional. 1 to 255 characters, naming this one action.
required: false
description: Optional. 1 to 255 characters, naming this one action.
name: idempotency-key
in: header
requestBody:
required: false
content:
application/json:
schema:
type: object
properties:
count:
type: integer
minimum: 1
maximum: 1000
description: 'How many uses the action takes: 1 to 1,000, 1 by default.'
responses:
'200':
description: Counted, or refused with why.
content:
application/json:
schema:
$ref: '#/components/schemas/Usage'
'400':
description: A parameter is missing or wrong; `param` names it.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
description: No key, a malformed or revoked one; or a site token that is not valid for this tool, or has ended.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: 'The workspace''s plan does not allow it: on Hobby, 100 passes at once.'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: No such tool, grant or person in this workspace.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: A request with this Idempotency-Key is still being answered.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
description: More than a minute's requests from this key, its workspace's or its owner's; the buyer's minute of asks; or the buyer's day of free uses.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
description: Toolaby's fault, or it cannot count the workspace's additions just now. Retry.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'503':
description: Toolaby cannot read or count the buyer's uses just now. Retry.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
operationId: postApiV1ToolsBySlugUses
x-operation-id-source: derived
components:
schemas:
Error:
type: object
properties:
error:
type: object
properties:
type:
type: string
enum:
- authentication_error
- invalid_request_error
- idempotency_error
- plan_limit_error
- not_found
- rate_limit_error
- api_error
message:
type: string
param:
type: string
required:
- type
- message
required:
- error
Usage:
type: object
properties:
object:
type: string
enum:
- usage
allowed:
type: boolean
description: Whether the action may go ahead. On POST, the uses are counted when it may.
entitled:
type: boolean
description: 'The buyer holds the tool: bought, subscribed, on a trial or granted. Nothing is counted.'
unlimited:
type: boolean
description: 'Nothing limits the buyer: they hold the tool, or it is open to everyone.'
used:
type: integer
remaining:
type: integer
limit:
type: integer
per:
type: string
enum:
- ever
- day
- week
- month
description: The period the free uses are counted in.
window:
type: string
description: 'For a period: when the current one began.'
resetsAt:
type: string
description: 'For a period: when the next one begins.'
reason:
type: string
enum:
- limit
- paid
description: 'Why not: the free uses are spent (`limit`), or the tool is sold only (`paid`).'
sharedUses:
type: boolean
description: 'The buyer''s address is a throwaway or unverified one: its uses are counted with every other such address''s.'
deviceLimit:
type: object
properties:
allowed:
type: integer
held:
type: integer
required:
- allowed
- held
description: 'For an extension''s token: its device is past the account''s device limit, and is counted as a free one.'
required:
- object
- allowed
- entitled
securitySchemes:
bearer:
type: http
scheme: bearer
description: 'An API key from the dashboard: wk_test_… or wk_live_….'