These guides follow the AI Agent Manifesto.
API reference
Find Hats, or submit a service request for Tinyhat's manual review.
OpenAPI 3.1 specification · MCP reference
| Method | Endpoint | What it does | Access |
|---|
POST | /api/service-requests | Submit a service request Save a job brief as a service request for Tinyhat's manual review when the user wants help seeking providers. Requires the owner's token and permission to share the file. Returns HTTP 202 with a unique service_request_id for retrieving the saved item and checking status. This does not contact providers or make a booking. | Bearer owner session |
GET | /api/service-requests | List Service Requests Check your recent home-service submissions and notification status. Requires the owner's token. Returns only your service-request receipts, newest first, without the job-brief text. | Bearer owner session |
GET | /api/service-requests/{service_request_id} | Get Service Request Reopen a service request using its service_request_id. Requires the same owner's token. Returns the saved job brief and receipt; another owner's item or a Hat-request ID returns 404. | Bearer owner session |
POST | /api/hat-requests | Request a missing Hat Tell Tinyhat which missing Hat would help your agent handle a chore. Requires the owner's token. Saves the question for manual review and returns HTTP 202 with a unique hat_request_id. It does not immediately create a Hat or arrange a service. | Bearer owner session |
GET | /api/hat-requests | List your Hat requests Check your requests for missing Hats. Requires the owner's token. Returns only your Hat-request receipts, newest first, without the saved questions. | Bearer owner session |
GET | /api/hat-requests/{hat_request_id} | Read your Hat request Reopen a missing-Hat request using its hat_request_id. Requires the same owner's token. Returns the saved question and receipt; another owner's item or a service-request ID returns 404. | Bearer owner session |
POST | /api/delegations | Submit Delegation Ask Tinyhat to take over provider finding using the exact authorized job file, service and city/region. Requires the existing owner's bearer session and explicit team-sharing permission. Returns a delegation_id, PENDING and a server decision_deadline within five minutes. PENDING and Slack delivery are not acceptance. Approval configuration and actual host authentication remain release gates. | Bearer owner session |
GET | /api/delegations/{delegation_id} | Get Delegation Status Read only your delegation's authoritative decision and deadline. Poll the same ID about every ten seconds and at the deadline. A failed read means uncertainty; recover the same ID. APPROVED transfers provider coordination only; reconcile parallel inquiries. No provider booking, payment or completion is implied. | Bearer owner session |
POST | /api/delegations/{delegation_id}/cancel | Cancel Delegation Cancel your pending delegation. An approved request cannot be undone by this operation; agree any handback with Tinyhat. Repeated cancellation returns the existing terminal state. | Bearer owner session |
DELETE | /api/delegations/{delegation_id}/content | Delete Delegation Content Permanently remove your backend delegation file and service/location labels after confirming irreversible removal. Cancels pending requests; approved provider coordination remains owned by Tinyhat until an agreed handback. Keeps the decision, hashes and retry record. Prior Slack copies may remain under workspace retention and cannot be recalled through the incoming webhook. Backend file removal is scheduled after 30 days, with owner removal available sooner. | Bearer owner session |
GET | /api/chores | Recent Chores Read up to twenty of your delegated chores, newest delegation first. Requires your verified owner session or linked OAuth token with chores:status. An optional cursor continues older records; another owner's records are never included. No job file, quote, appointment or completion is inferred. | Bearer owner session |
GET | /api/chores/{chore_id} | Chore Detail Read a minimal description, delegation timestamp, status and ID for your own chore. Requires the same verified owner session. Another owner's or missing ID returns 404. This does not change, book or cancel a chore. | Bearer owner session |
GET | /api/hats | Find Hats Describe a chore and location to find relevant Hats. Use this first to choose what to read. Returns up to ten ranked Markdown Hat links; no sign-in is required. | Anonymous |
GET | /api/hats/content/{path} | Read a Hat Read a Hat using a path returned by search. It explains what providers need and how an agent can progress the chore. Returns the exact Markdown shown on the Hat page and download; no sign-in is required. | Anonymous |
POST | https://apii.tinyloop.co/hapi/v2/auth/email/request | Request Email Code Start the existing Tinyhat email sign-in flow when the owner has authorized it. Returns a challenge ID and expiry without revealing whether an account exists. It sends a one-time code to that email; never log the code. | Anonymous |
POST | https://apii.tinyloop.co/hapi/v2/auth/email/verify | Verify Email Code Complete the email challenge with the owner's matching code. Returns the existing expiring owner bearer session and account information. Keep the token private; this does not submit a service request. | Anonymous |
DELETE | /auth/session | Sign Out Revoke only the current owner's bearer session. Requires that token and returns HTTP 204. Saved service requests are retained; no provider is contacted. | Bearer owner session |
Search
q is 1-300 characters, location is optional (up to 150), and limit is 1-10. Default search uses Tinyhat's catalogue and does not send the query to a model provider. Set use_model=true only with explicit permission to share this query and city/region with OpenAI Decisions. No file, account details, credentials or chat history are sent. Every service is scored; only existing Hat paths can be returned. Token usage and hashed input identifiers are recorded, without raw search text. Identical searches reuse a bounded memory cache.
Authentication
Writes and receipts use the existing Tinyhat email-code bearer session. Reading Hats needs no token. Call the existing API issuer directly from your agent: https://apii.tinyloop.co/hapi/v2/auth/email/request and https://apii.tinyloop.co/hapi/v2/auth/email/verify. These two calls are not proxied by the website, so different callers retain their own sign-in budgets. Sign out at DELETE https://tinyhat.ai/chore/auth/session. The verification response supplies the expiring bearer; never put it in a URL, uploaded file or logs. The existing real email-code sign-in flow has passed DEV acceptance. Keep codes and tokens out of submitted files.
Submit a service request
Ask the user before sharing the complete job brief with Tinyhat's review team and the configured Slack channel audience. Set X-Tinyhat-Share-With-Team: true only after this permission. Supply the job brief as a UTF-8 .md, .txt or .json file up to 64 KiB. Use a simple filename, a new retry key for each distinct service request, and the same key when retrying that item. A successful submission returns HTTP 202 with a receipt containing a unique service_request_id. Use it with GET /api/service-requests/{service_request_id} and the same owner's token to retrieve the saved content and check its status. This confirms receipt, not provider contact or booking. Maximum 20 submissions per account per day. Unsupported content types return 415, oversized bodies 413, retry-key conflicts 409, and invalid content 422.
curl -X POST https://tinyhat.ai/chore/api/service-requests \
-H 'Authorization: Bearer YOUR_SESSION_TOKEN' \
-H 'X-Tinyhat-Share-With-Team: true' -H 'Idempotency-Key: synthetic-chore-001' \
-H 'X-File-Name: request.md' -H 'Content-Type: text/markdown' \
--data-binary @request.md
Request a missing Hat
curl -X POST https://tinyhat.ai/chore/api/hat-requests \
-H 'Authorization: Bearer YOUR_SESSION_TOKEN' \
-H 'X-Tinyhat-Share-With-Team: true' -H 'Idempotency-Key: synthetic-guide-001' -H 'Content-Type: application/json' \
--data '{"question":"How can my agent arrange an annual chimney inspection with less back-and-forth?"}'
The question is 8-4,000 characters. Omit household identity or contact details. A Hat request returns a unique hat_request_id; retrieve it with GET /api/hat-requests/{hat_request_id}. List your items with GET /api/service-requests?limit=20 or GET /api/hat-requests?limit=20 (maximum 100). The same owner's bearer is required. Other owners receive 404.
What a receipt means
RECEIVED means saved for manual triage. It does not mean a provider was found, contacted or booked. Notification delivery is separate: BLOCKED, SENDING, DELIVERED, FAILED or UNKNOWN. UNKNOWN/SENDING are not automatically resent. Delivery requires the explicit team-sharing header. When explicitly enabled, the two business submission notifications include the summary, unique ID and complete accepted body. Only the submitted business body is included; HTTP headers, bearer credentials, cookies and sign-in codes are excluded. Recognizable credential fields or token patterns in a body return 422, rather than being silently removed. These checks cannot detect every secret in arbitrary text: never submit credentials. Bodies up to 64 KiB are split into numbered plain-text sections within one Slack message, with byte count and checksum. No silent truncation. Consented business submissions use the existing environment-specific hooks. If delivery is unconfigured, the item is still saved and its receipt shows BLOCKED. Sign-in and MCP protocol POSTs are never routed by this notifier.