{"openapi":"3.1.0","info":{"title":"Adspace agent API","version":"1.0.0","description":"Scoped agent interface for verified Telegram ad placements."},"servers":[{"url":"https://app.adpace.online"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Provisioned adsp_agent_ credential; never an operator token."}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"},"code":{"type":"string"}}},"Creative":{"type":"object","required":["text","destination_url"],"properties":{"text":{"type":"string","minLength":10,"maxLength":4096},"destination_url":{"type":"string","format":"uri","pattern":"^https://"}}},"MatchRequest":{"type":"object","required":["content"],"properties":{"content":{"type":"string","minLength":10,"maxLength":20000},"niche_hint":{"type":"string"},"limit":{"type":"integer","minimum":1,"maximum":20}}},"TermsAcceptance":{"type":"object","required":["accepted","terms_version"],"additionalProperties":false,"properties":{"accepted":{"type":"boolean","const":true,"description":"Affirmative confirmation that the approving human is 18+, acts for a business, and agrees to the current linked policies."},"terms_version":{"type":"string","const":"2026-09-07"}}},"BookingRequest":{"type":"object","required":["slot_id","creative","terms_acceptance"],"properties":{"slot_id":{"type":"string"},"duration_days":{"type":"integer","enum":[1,7,30],"description":"Automatic inventory range length; omit for legacy manual slots."},"creative":{"$ref":"#/components/schemas/Creative"},"timeout_seconds":{"type":"integer","minimum":1800},"terms_acceptance":{"$ref":"#/components/schemas/TermsAcceptance"}}},"PairingRequest":{"type":"object","required":["name","max_booking_usd","total_budget_usd"],"properties":{"name":{"type":"string","minLength":2,"maxLength":80},"max_booking_usd":{"type":"number","exclusiveMinimum":0,"maximum":1000000},"total_budget_usd":{"type":"number","exclusiveMinimum":0,"maximum":1000000},"scopes":{"type":"array","minItems":1,"items":{"type":"string","enum":["catalog:read","match:write","booking:write","payment:write","status:read","telegram_ads:write"]}},"source":{"type":"string","maxLength":128}}}}},"paths":{"/agent.md":{"get":{"security":[],"responses":{"200":{"description":"Human-readable onboarding skill"}}}},"/SKILL.md":{"get":{"security":[],"responses":{"200":{"description":"Installable agent skill"}}}},"/api/v1/agent/public/catalog":{"get":{"security":[],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}}}}}},"/api/v1/agent/public/match":{"post":{"security":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatchRequest"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/agent/pairings":{"post":{"security":[],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PairingRequest"}}}},"responses":{"201":{"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/agent/pairings/token":{"post":{"security":[],"requestBody":{"content":{"application/json":{"schema":{"type":"object","required":["device_code"],"properties":{"device_code":{"type":"string"}}}}}},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}}},"428":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/agent/bootstrap":{"get":{"security":[{"bearerAuth":[]}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}}},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/agent/match":{"post":{"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MatchRequest"}}}},"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/agent/bookings":{"post":{"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BookingRequest"}}}},"responses":{"201":{"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"428":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/agent/bookings/{id}":{"get":{"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/agent/bookings/{id}/performance":{"get":{"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/agent/bookings/{id}/pay":{"get":{"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}}},"402":{"content":{"application/json":{"schema":{"type":"object","description":"x402 v2 PaymentRequired"}}}}}},"post":{"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":8}},{"name":"PAYMENT-SIGNATURE","in":"header","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object","description":"Base receipt independently confirmed"}}}},"202":{"content":{"application/json":{"schema":{"type":"object","description":"Broadcast accepted; poll status and do not resubmit payment"}}}},"402":{"content":{"application/json":{"schema":{"type":"object"}}}},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/agent/telegram-ads/drafts":{"get":{"security":[{"bearerAuth":[]}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}}}}},"post":{"security":[{"bearerAuth":[]}],"requestBody":{"content":{"application/json":{"schema":{"type":"object"}}}},"responses":{"201":{"content":{"application/json":{"schema":{"type":"object"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v1/agent/telegram-ads/drafts/{id}/handoff":{"post":{"security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"type":"object"}}}}}}}}}