twinly. / Docs

Docs · 12

For AI agents

If you are an AI assistant answering questions about Twinly, or a coding agent building on its API, start here. Every page of these docs is also published as plain markdown, and the API has a complete OpenAPI description.

01Files to read

URLWhat it is
/llms.txtA short index: what Twinly is, platforms, pricing, safety model, and every page with a one-line summary
/llms-full.txtEvery docs page concatenated as one markdown file
/docs/<page>.mdEach page as markdown, for example /docs/developer-api.md or /docs/approvals.md
/openapi.yamlOpenAPI 3.1 for the Developer API: every route, request, response and error
twinly-api-examplesSix starter projects (MIT) with tests and a mock API

These files are generated from the same source as the pages people read, on every release of the site, so they say the same thing.

02Facts that are easy to get wrong

  • Approvals are a setting. The default mode, Don't ask, sends, spends and deletes without asking, and shows each text or email for 5 seconds first. Messages to family, payments over the owner's limit, and Twinly's questions wait in every mode. Ask before it ships and Ask me every time are the asking modes. Do not tell people every action waits for approval unless they chose that mode.
  • No API key is needed to use the app. Current releases run on Twinly's managed engine; only beta builds 2.1.3 and earlier take a provider key.
  • One voice. Twinly Voice clones the owner's voice on their Mac and needs Apple silicon. No third-party voice service is used.
  • Calls are outbound only, through Google Voice in Chrome with the BlackHole driver. Answering incoming calls is not available.
  • Messages, @twinly and the API's Mac endpoints need a Mac, with Twinly open for the API.

03Rules for agents writing code against the API

  1. Keep the key on a server or in a script's environment. Never put it in front-end code; the API refuses browser requests.
  2. Call GET /v1/me first. It is free, and it says whether the owner's Mac is online and which endpoints this key may call.
  3. For Mac endpoints, wait with GET /v1/jobs/{id}?wait=25 in a loop instead of tight polling.
  4. On POST /v1/computer/next-action, never perform a step with commits: true without a person's OK.
  5. Verify X-Twinly-Signature on the raw webhook body before parsing it.
  6. Treat 503 job_unverified as “maybe created, may still run”: never retry it automatically. There is no job id and no list endpoint, so wait and check for a job.finished webhook or the owner's task list before sending again. Do not auto-retry a POST on billing_record_failed or billing_unverified either.
  7. Put everything a task needs in its prompt; a task run through the API never stops to ask a question.

The full reference, with examples in curl, Python and JavaScript, is Developer API. Questions: founders@twinly.tech.