{"openapi":"3.1.0","info":{"title":"Specialty Tokens agent inquiry API","version":"1.1.0","description":"Public, unauthenticated endpoints for AI agents to book an intro call with Specialty Tokens, or to request bespoke AI development, an internal AI ops platform, or corporate AI training, on behalf of a client in DACH, London or Amsterdam.","contact":{"name":"Specialty Tokens","email":"frida@specialtytokens.com","url":"https://specialtytokens.com/agents"}},"servers":[{"url":"https://specialtytokens.com"}],"paths":{"/api/agents/inquiry":{"post":{"operationId":"submitAgentInquiry","summary":"Submit an engagement inquiry on behalf of a principal","description":"Creates a lead the team reviews within one business day. Rate limited per IP. Retries with the same inquiryId are idempotent.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentInquiry"}}}},"responses":{"200":{"description":"Inquiry received","content":{"application/json":{"schema":{"$ref":"#/components/schemas/InquiryReceipt"}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; honour Retry-After"},"502":{"description":"Lead could not be relayed; retry later or email frida@specialtytokens.com"}}}},"/api/agents/slots":{"get":{"operationId":"listIntroCallSlots","summary":"Open 30 minute intro-call slots","description":"Live availability from Cal.com. Pass one slot's start to bookIntroCall. Rate limited per IP.","parameters":[{"name":"timeZone","in":"query","required":false,"schema":{"type":"string","default":"Europe/Vienna"},"description":"IANA time zone for the returned times."},{"name":"from","in":"query","required":false,"schema":{"type":"string","format":"date"},"description":"First day to search. Defaults to today."},{"name":"days","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":21,"default":7}}],"responses":{"200":{"description":"Open slots","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Slots"}}}},"400":{"description":"Invalid query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limited; honour Retry-After"},"502":{"description":"Availability could not be read; retry later"}}}},"/api/agents/book":{"post":{"operationId":"bookIntroCall","summary":"File an inquiry and book the intro call in one request","description":"Needs the principal's company email; personal mailboxes get the prefilled booking link instead. Cal.com sends the invite. If the slot is gone (409) the inquiry is still filed: retry with another slot and the same inquiryId.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentBooking"}}}},"responses":{"200":{"description":"Booked, or held for our confirmation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookingReceipt"}}}},"400":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Inquiry filed, slot not booked","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookingReceipt"}}}},"429":{"description":"Rate limited; honour Retry-After"},"502":{"description":"Inquiry filed, calendar did not answer","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookingReceipt"}}}}}}},"/api/agents/openapi.json":{"get":{"operationId":"getOpenApi","summary":"This document","responses":{"200":{"description":"OpenAPI 3.1 JSON"}}}},"/agents.json":{"get":{"operationId":"getAgentManifest","summary":"Agent manifest (services, regions, endpoints)","responses":{"200":{"description":"JSON manifest"}}}}},"components":{"schemas":{"AgentInquiry":{"type":"object","properties":{"agent":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120,"description":"Name of the agent or assistant submitting this, e.g. 'Claude', 'Acme Procurement Agent'."},"operator":{"type":"string","maxLength":200},"contactUrl":{"type":"string","format":"uri","maxLength":500}},"required":["name"],"additionalProperties":false,"description":"The software agent making the request."},"principal":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Full name of the person we should reply to."},"email":{"type":"string","format":"email","maxLength":320,"description":"Work email of the principal. We reply here."},"company":{"type":"string","minLength":1,"maxLength":300,"description":"Company or organisation name."},"role":{"type":"string","maxLength":200},"phone":{"type":"string","maxLength":80},"companySize":{"type":"string","enum":["1-25","26-100","101-500","501-5000","5000+"]},"website":{"type":"string","format":"uri","maxLength":500}},"required":["name","email","company"],"additionalProperties":false,"description":"The human decision maker the agent acts for."},"request":{"type":"object","properties":{"service":{"type":"string","enum":["bespoke-ai-development","internal-ai-ops-platform","corporate-ai-training"],"description":"Which engagement the principal is exploring."},"region":{"type":"string","enum":["dach","london","amsterdam"],"description":"Where delivery should happen."},"summary":{"type":"string","minLength":20,"maxLength":4000,"description":"What the principal wants, in plain language: systems involved, the workflow, the outcome."},"timeline":{"type":"string","enum":["asap","within-1-month","within-3-months","exploring"]},"budgetBand":{"type":"string","enum":["under-25k-eur","25k-75k-eur","75k-200k-eur","over-200k-eur","undisclosed"]},"language":{"type":"string","enum":["en","de"],"description":"Preferred language for our reply."},"preferredSlots":{"type":"array","items":{"type":"string","format":"date-time"}},"references":{"type":"array","items":{"type":"string","format":"uri","maxLength":500}}},"required":["service","region","summary"],"additionalProperties":false,"description":"The engagement being requested."},"inquiryId":{"type":"string"},"website":{"type":"string","maxLength":200}},"required":["agent","principal","request"],"additionalProperties":false},"InquiryReceipt":{"type":"object","properties":{"ok":{"const":true},"inquiryId":{"type":"string","description":"Echo of the idempotency key; quote it in follow-ups."},"status":{"const":"received"},"nextStep":{"type":"string"},"bookingUrl":{"type":"string","format":"uri","description":"Intro-call booking link for the principal, prefilled with their details."},"replyTo":{"type":"string","format":"email"},"responseTime":{"type":"string"}},"required":["ok","inquiryId","status","nextStep","bookingUrl","replyTo","responseTime"]},"AgentBooking":{"type":"object","properties":{"agent":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":120,"description":"Name of the agent or assistant submitting this, e.g. 'Claude', 'Acme Procurement Agent'."},"operator":{"type":"string","maxLength":200},"contactUrl":{"type":"string","format":"uri","maxLength":500}},"required":["name"],"additionalProperties":false,"description":"The software agent making the request."},"principal":{"type":"object","properties":{"name":{"type":"string","minLength":1,"maxLength":200,"description":"Full name of the person we should reply to."},"email":{"type":"string","format":"email","maxLength":320,"description":"Work email of the principal. We reply here."},"company":{"type":"string","minLength":1,"maxLength":300,"description":"Company or organisation name."},"role":{"type":"string","maxLength":200},"phone":{"type":"string","maxLength":80},"companySize":{"type":"string","enum":["1-25","26-100","101-500","501-5000","5000+"]},"website":{"type":"string","format":"uri","maxLength":500}},"required":["name","email","company"],"additionalProperties":false,"description":"The human decision maker the agent acts for."},"request":{"type":"object","properties":{"service":{"type":"string","enum":["bespoke-ai-development","internal-ai-ops-platform","corporate-ai-training"],"description":"Which engagement the principal is exploring."},"region":{"type":"string","enum":["dach","london","amsterdam"],"description":"Where delivery should happen."},"summary":{"type":"string","minLength":20,"maxLength":4000,"description":"What the principal wants, in plain language: systems involved, the workflow, the outcome."},"timeline":{"type":"string","enum":["asap","within-1-month","within-3-months","exploring"]},"budgetBand":{"type":"string","enum":["under-25k-eur","25k-75k-eur","75k-200k-eur","over-200k-eur","undisclosed"]},"language":{"type":"string","enum":["en","de"],"description":"Preferred language for our reply."},"preferredSlots":{"type":"array","items":{"type":"string","format":"date-time"}},"references":{"type":"array","items":{"type":"string","format":"uri","maxLength":500}}},"required":["service","region","summary"],"additionalProperties":false,"description":"The engagement being requested."},"inquiryId":{"type":"string"},"website":{"type":"string","maxLength":200},"booking":{"type":"object","properties":{"start":{"type":"string","format":"date-time","description":"Start of the call, exactly as returned by get_available_slots or GET /api/agents/slots."},"timeZone":{"type":"string","maxLength":64,"description":"The principal's IANA time zone, e.g. Europe/Berlin. The calendar invite uses it."}},"required":["start","timeZone"],"additionalProperties":false,"description":"The 30 minute intro call to book."}},"required":["agent","principal","request","booking"],"additionalProperties":false},"BookingReceipt":{"type":"object","properties":{"ok":{"type":"boolean"},"inquiryId":{"type":"string","description":"Reuse it when retrying with another slot."},"status":{"enum":["booked","pending-confirmation","not-booked"]},"booking":{"type":"object","properties":{"uid":{"type":"string"},"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"},"timeZone":{"type":"string"},"bookingPage":{"type":"string","format":"uri","description":"Cal.com page where the principal can reschedule or cancel."},"location":{"type":"string"}},"required":["uid","start","end","timeZone","bookingPage"]},"reason":{"type":"string","description":"Why the call was not booked."},"nextStep":{"type":"string"},"bookingUrl":{"type":"string","format":"uri","description":"Prefilled link the principal can use to pick a time themselves."},"replyTo":{"type":"string","format":"email"},"responseTime":{"type":"string"}},"required":["ok","inquiryId","status","nextStep","bookingUrl","replyTo","responseTime"]},"Slots":{"type":"object","properties":{"timeZone":{"type":"string"},"durationMinutes":{"type":"integer"},"from":{"type":"string","format":"date"},"to":{"type":"string","format":"date"},"slots":{"type":"array","items":{"type":"object","properties":{"start":{"type":"string","format":"date-time"},"end":{"type":"string","format":"date-time"}},"required":["start","end"]}},"bookWith":{"type":"string"}},"required":["timeZone","durationMinutes","from","to","slots"]},"Error":{"type":"object","properties":{"error":{"type":"string"},"field":{"type":["string","null"],"description":"Dotted path of the failing field, e.g. request.summary"}},"required":["error"]}}}}