{"openapi":"3.1.0","info":{"title":"Two Unknowns Agent Access API","version":"1.0.0","description":"Discover real, named human talent with source-linked credentials, compare public services and indicative pricing, perform privacy-preserving date checks, and submit booking requests for human review. No API response constitutes a confirmed booking.","contact":{"name":"Two Unknowns","url":"https://twounknowns.com/contact"},"termsOfService":"https://twounknowns.com/terms"},"servers":[{"url":"https://twounknowns.com","description":"Production"}],"tags":[{"name":"Talent"},{"name":"Availability"},{"name":"Bookings"}],"paths":{"/api/v1/talent":{"get":{"operationId":"searchTalent","tags":["Talent"],"summary":"Search public talent profiles","parameters":[{"name":"q","in":"query","schema":{"type":"string"},"description":"Words describing expertise, service, role or location"},{"name":"max_budget","in":"query","schema":{"type":"number"},"description":"Maximum indicative budget in AUD"}],"responses":{"200":{"description":"Matching public profiles","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Talent"}}}}}}}}}},"/api/v1/talent/{slug}":{"get":{"operationId":"getTalent","tags":["Talent"],"summary":"Get one public talent profile","parameters":[{"name":"slug","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Public profile"},"404":{"description":"Profile not found"}}}},"/api/v1/availability-checks":{"post":{"operationId":"checkAvailability","tags":["Availability"],"summary":"Perform a privacy-preserving indicative date check","description":"Returns only a safe conclusion. It never reveals calendar entries and never confirms a booking.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["slug","eventDate"],"properties":{"slug":{"type":"string"},"eventDate":{"type":"string","format":"date"},"serviceId":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"Indicative date result"},"400":{"description":"Invalid request"}}}},"/api/v1/booking-requests":{"post":{"operationId":"createBookingRequest","tags":["Bookings"],"summary":"Submit a booking request for manager review","description":"The agent must have its human principal's approval. Send a unique Idempotency-Key header. A successful response is an enquiry, not a booking.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","maxLength":180}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookingRequest"}}}},"responses":{"201":{"description":"Request received. The returned statusToken is shown once."},"400":{"description":"Invalid request or principal approval missing"}}}},"/api/v1/booking-requests/{reference}":{"get":{"operationId":"getBookingStatus","tags":["Bookings"],"summary":"Get a booking-request status","security":[{"statusToken":[]}],"parameters":[{"name":"reference","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Sanitised request status"},"404":{"description":"Not found or token invalid"}}}}},"components":{"securitySchemes":{"statusToken":{"type":"apiKey","in":"header","name":"X-Booking-Status-Token","description":"One-time status token returned when the request is created"}},"schemas":{"Service":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"category":{"type":"string"},"description":{"type":"string"},"currency":{"type":"string","example":"AUD"},"indicative_min":{"type":"number"},"indicative_max":{"type":"number"},"travel_required":{"type":"boolean"},"recording_terms":{"type":"string"}}},"HumanTrust":{"type":"object","description":"Machine-readable safeguards for human talent.","properties":{"identityDisclosed":{"type":"boolean","const":true},"credentialsSourceLinked":{"type":"boolean","const":true},"humanApprovalRequired":{"type":"boolean","const":true},"syntheticSubstitutionAllowed":{"type":"boolean","const":false},"aiRightsRequireExplicitAgreement":{"type":"boolean","const":true}}},"Talent":{"type":"object","properties":{"slug":{"type":"string"},"humanTalent":{"type":"boolean","const":true},"trust":{"$ref":"#/components/schemas/HumanTrust"},"name":{"type":"string"},"profileUrl":{"type":"string","format":"uri"},"mediaKitUrl":{"type":"string","format":"uri"},"profile":{"type":"object"},"services":{"type":"array","items":{"$ref":"#/components/schemas/Service"}},"credits":{"type":"array","items":{"type":"object"}}}},"BookingRequest":{"type":"object","required":["slug","serviceId","requesterName","requesterEmail","organizationName","eventName","location","message","principalConfirmed"],"properties":{"slug":{"type":"string"},"serviceId":{"type":"string","format":"uuid"},"requesterName":{"type":"string"},"requesterEmail":{"type":"string","format":"email"},"organizationName":{"type":"string"},"eventName":{"type":"string"},"eventDate":{"type":"string","format":"date"},"location":{"type":"string"},"budget":{"type":"number"},"currency":{"type":"string","default":"AUD"},"audienceSize":{"type":"integer"},"recordingRequested":{"type":"boolean"},"travelCovered":{"type":"boolean"},"requestedRights":{"type":"string"},"message":{"type":"string"},"agentName":{"type":"string"},"agentVersion":{"type":"string"},"principalConfirmed":{"type":"boolean","const":true},"callbackUrl":{"type":"string","format":"uri"}}}}}}