Function API

A Function API sells an answer computed when asked. Each Verb names its Function kind, which sets how long the answer takes and what it costs you. The caller sees one Verb, one price and one Action, whichever kind does the work.

import { define, code, generative, agentic, human, escalate } from 'apis.dev'
import { sectorFromTable } from './sectors'

/** Answers about any company by its domain, from a score in milliseconds to a person's check in hours. */
export default define({
  name: 'summaries', domain: 'summaries.apis.dev',
  Company: {
    domain:    'url!#',
    score:     code((c) => ({ score: c.domain.endsWith('.ai') ? 80 : 50 })),     // computes
    summarize: generative('Two sentences on what {domain} sells',                 // writes
      { returns: { summary: 'string' } }),
    research:  agentic('Find the head of sales at {domain}',                      // researches
      { returns: { headOfSales: 'string' } }),
    verify:    human('Call and confirm the head of sales',                        // decides
      { role: 'researcher', within: '24h', returns: { confirmed: 'boolean' } }),
    classify:  escalate([                                                         // one Verb, three kinds
      code(sectorFromTable),
      generative('The sector {domain} sells into, from the list'),
      human('Read the site and pick the sector', { role: 'researcher', within: '24h' }),
    ], { returns: { sector: 'string' }, check: (out) => out.sector !== 'unknown' }),
  },
  Text: {                                                                         // on no stored Noun
    translate: generative('Translate {text} into {to}',
      { input: { text: 'string', to: 'string' }, returns: { text: 'string' } }),
  },
  offer: {
    'Company.score': 0.001, 'Company.summarize': 0.02,
    'Company.research': 0.5, 'Company.verify': 5,
    'Company.classify': 0.04,                    // one price, whichever kind answers
    'Text.translate': 0.01,
  },
})

The four kindsCopy Anchor Link

returns types the output on every Interface: the Action, the MCP outputSchema, OpenAPI and the SDK. A generative or agentic answer is stamped Inferred, and a person's answer Stated, so the caller knows the basis of every value.

EscalationCopy Anchor Link

escalate puts several kinds behind one Verb, cheapest first. Each rung runs only when the one before fails the Verb's check, so a person sees only the hard calls. The rungs are private: the caller sees the Action, its reason while it waits, and the Provenance of the answer.

A domain the table and the model both miss reaches a researcher. The call answers at once, and the Action waits on the person.

curl -X POST https://summaries.apis.dev/companies/obscure.io/classify \
  -H "Authorization: Bearer $SUMMARIES_KEY" \
  -H "Max-Cost: 0.10"

HTTP/1.1 202 Accepted
Location: /actions/act_4
Retry-After: 3600
X-Cost: price=0.04, currency="USD"
X-Request-Id: req_3e81c0d47a9b52f61e07

{
  "id": "act_4",
  "verb": "Company.classify",
  "status": "pending",
  "reason": "AwaitingWorker",
  "until": "2026-10-28T09:00:00Z",
  "poll": "/actions/act_4"
}

When the researcher answers, the Action is done with "provenance": "Stated", and its receipt names the Version and the $0.04. If no one claims the task by until, it fails, and the reserved price is released.

Pricing by kindCopy Anchor Link

A Function API is priced per call, and each Verb has its own price. The kinds set the usual range: $0.001 to compute, $0.02 to write, $0.5 to research, $5 for a person. A failed or cancelled Action costs nothing, and a call above its Max-Cost is refused before it runs.

An escalating Verb has one price. When a call climbs to a dearer rung, you carry the difference, and the caller pays the same $0.04.

Deploy prints your margin at the rate each rung was reached over the last 10,000 calls, or at the Test twin's estimate at first. A price below that cost is refused with below_cost.

$ npx apis.dev deploy
✓ Company.classify  0.04  · code 100% · generative 30% · human 1% · cost 0.0213 · margin 47%
✓ published v4 to https://summaries.apis.dev

The print is yours alone. As the model answers more of the hard calls, the human rate falls and the margin rises. The Verb and its price stay the same.

Contracts and the platform's partCopy Anchor Link

What Customers and their agents meetCopy Anchor Link

• A price before the call. /pricing and the offer card list each Verb's price, and quote returns it at no charge.
• One Action for every kind. A fast kind answers done; a slow one answers 202 with where to poll, or holds the call open with Prefer: wait.
• The basis of every answer. Provenance says whether code, a model or a person wrote it.
• No charge for a miss. A failed, lapsed or cancelled Action costs nothing.

An agent finishes the same path with no UI:

1. It reads the offer card: price per Verb, success rate and median time, judged from outside.
2. It calls classifyCompany over MCP with Max-Cost, under its mandate.
3. It subscribes to the Action and resumes on done, with no polling.
4. It keeps the signed receipt, and disputes with it when the answer misses the terms.