{"openapi":"3.0.3","info":{"title":"Hibiki Public API","description":"REST API for Hibiki — WhatsApp + Meta Ads platform for LATAM SMBs.","version":"1.1.0","contact":{"name":"Hibiki","url":"https://hibik.io"}},"servers":[{"url":"https://hibik.io/api/v1","description":"Current host"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"Me","description":"Workspace + key metadata"},{"name":"Contacts"},{"name":"ContactLists"},{"name":"Tags"},{"name":"Segments"},{"name":"Broadcasts"},{"name":"Campaigns"},{"name":"Conversations"},{"name":"Messages"},{"name":"WebhookEndpoints"}],"paths":{"/me":{"get":{"tags":["Me"],"summary":"Fetch workspace + API key info","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"MeResponse","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MeResponse"}}}}}}},"/contacts":{"get":{"tags":["Contacts"],"summary":"List contacts","security":[{"bearerAuth":[]}],"parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string"}},{"name":"opt_in_status","in":"query","required":false,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"string"}},{"name":"per_page","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Contact"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}}}},"post":{"tags":["Contacts"],"summary":"Create contact","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactInput"}}}},"responses":{"201":{"description":"Contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/contacts/batch":{"post":{"tags":["Contacts"],"summary":"Bulk upsert up to 500 contacts by phone_number","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchContactsRequest"}}}},"responses":{"202":{"description":"Batch accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchResult"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/contacts/{id}":{"get":{"tags":["Contacts"],"summary":"Fetch contact","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Contacts"],"summary":"Update contact","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactInput"}}}},"responses":{"200":{"description":"Contact","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Contacts"],"summary":"Delete contact","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted"}}}},"/contact_lists":{"get":{"tags":["ContactLists"],"summary":"List contactlists","security":[{"bearerAuth":[]}],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"string"}},{"name":"per_page","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ContactList"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}}}},"post":{"tags":["ContactLists"],"summary":"Create list","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactListInput"}}}},"responses":{"201":{"description":"ContactList","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactList"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/contact_lists/{id}":{"get":{"tags":["ContactLists"],"summary":"Fetch contactlist","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"ContactList","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactList"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["ContactLists"],"summary":"Update contactlist","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactListInput"}}}},"responses":{"200":{"description":"ContactList","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactList"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["ContactLists"],"summary":"Delete contactlist","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted"}}}},"/contact_lists/{contact_list_id}/memberships":{"post":{"tags":["ContactLists"],"summary":"Add contact to list","security":[{"bearerAuth":[]}],"parameters":[{"name":"contact_list_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MembershipInput"}}}},"responses":{"201":{"description":"Membership","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Membership"}}}}}}},"/contact_lists/{contact_list_id}/memberships/{id}":{"delete":{"tags":["ContactLists"],"summary":"Remove contact from list","security":[{"bearerAuth":[]}],"parameters":[{"name":"contact_list_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Removed"}}}},"/tags":{"get":{"tags":["Tags"],"summary":"List tags","security":[{"bearerAuth":[]}],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"string"}},{"name":"per_page","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Tag"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}}}},"post":{"tags":["Tags"],"summary":"Create tag","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagInput"}}}},"responses":{"201":{"description":"Tag","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Tag"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tags/batch":{"post":{"tags":["Tags"],"summary":"Bulk upsert up to 200 tags by name","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchTagsRequest"}}}},"responses":{"202":{"description":"Batch accepted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BatchResult"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/tags/{id}":{"patch":{"tags":["Tags"],"summary":"Update tag","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TagInput"}}}},"responses":{"200":{"description":"Tag","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Tag"}}}}}},"delete":{"tags":["Tags"],"summary":"Delete tag","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted"}}}},"/segments":{"get":{"tags":["Segments"],"summary":"List segments","security":[{"bearerAuth":[]}],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"string"}},{"name":"per_page","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Segment"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}}}},"post":{"tags":["Segments"],"summary":"Create segment","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SegmentInput"}}}},"responses":{"201":{"description":"Segment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Segment"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/segments/{id}":{"get":{"tags":["Segments"],"summary":"Fetch segment","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Segment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Segment"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Segments"],"summary":"Update segment","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SegmentInput"}}}},"responses":{"200":{"description":"Segment","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Segment"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Segments"],"summary":"Delete segment","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted"}}}},"/broadcasts":{"get":{"tags":["Broadcasts"],"summary":"List broadcasts","security":[{"bearerAuth":[]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"string"}},{"name":"per_page","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Broadcast"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}}}},"post":{"tags":["Broadcasts"],"summary":"Create broadcast","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BroadcastInput"}}}},"responses":{"201":{"description":"Broadcast","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Broadcast"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/broadcasts/{id}":{"get":{"tags":["Broadcasts"],"summary":"Fetch broadcast","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Broadcast","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Broadcast"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Broadcasts"],"summary":"Update broadcast","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BroadcastInput"}}}},"responses":{"200":{"description":"Broadcast","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Broadcast"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Broadcasts"],"summary":"Delete broadcast","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted"}}}},"/broadcasts/{id}/schedule":{"post":{"tags":["Broadcasts"],"summary":"Schedule broadcast","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Broadcast","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Broadcast"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/broadcasts/{id}/cancel":{"post":{"tags":["Broadcasts"],"summary":"Cancel broadcast","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Broadcast","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Broadcast"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/campaigns":{"get":{"tags":["Campaigns"],"summary":"List campaigns","security":[{"bearerAuth":[]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"string"}},{"name":"per_page","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Campaign"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}}}},"post":{"tags":["Campaigns"],"summary":"Create ad campaign","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignInput"}}}},"responses":{"201":{"description":"Campaign","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/campaigns/{id}":{"get":{"tags":["Campaigns"],"summary":"Fetch campaign","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Campaign","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"patch":{"tags":["Campaigns"],"summary":"Update campaign","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CampaignInput"}}}},"responses":{"200":{"description":"Campaign","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["Campaigns"],"summary":"Delete campaign","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted"}}}},"/campaigns/{id}/publish":{"post":{"tags":["Campaigns"],"summary":"Publish campaign to Meta","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Campaign","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/campaigns/{id}/pause":{"post":{"tags":["Campaigns"],"summary":"Pause campaign","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Campaign","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/campaigns/{id}/resume":{"post":{"tags":["Campaigns"],"summary":"Resume campaign","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Campaign","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Campaign"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/conversations":{"get":{"tags":["Conversations"],"summary":"List conversations","security":[{"bearerAuth":[]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string"}},{"name":"contact_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"attributed","in":"query","required":false,"schema":{"type":"string"}},{"name":"since","in":"query","required":false,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"string"}},{"name":"per_page","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Conversation"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}}}}},"/conversations/{id}":{"get":{"tags":["Conversations"],"summary":"Fetch conversation","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Conversation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Conversation"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/messages":{"get":{"tags":["Messages"],"summary":"List messages","security":[{"bearerAuth":[]}],"parameters":[{"name":"conversation_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"contact_id","in":"query","required":false,"schema":{"type":"string"}},{"name":"direction","in":"query","required":false,"schema":{"type":"string"}},{"name":"status","in":"query","required":false,"schema":{"type":"string"}},{"name":"since","in":"query","required":false,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"string"}},{"name":"per_page","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Message"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}}}},"post":{"tags":["Messages"],"summary":"Send an outbound message","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/MessageInput"}}}},"responses":{"201":{"description":"Message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}}},"400":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/messages/{id}":{"get":{"tags":["Messages"],"summary":"Fetch message","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Message","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Message"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhook_endpoints":{"get":{"tags":["WebhookEndpoints"],"summary":"List webhookendpoints","security":[{"bearerAuth":[]}],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"string"}},{"name":"per_page","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookEndpoint"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}}}},"post":{"tags":["WebhookEndpoints"],"summary":"Register webhook","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpointInput"}}}},"responses":{"201":{"description":"WebhookEndpoint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhook_endpoints/{id}":{"get":{"tags":["WebhookEndpoints"],"summary":"Fetch webhookendpoint","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"WebhookEndpoint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"delete":{"tags":["WebhookEndpoints"],"summary":"Delete webhookendpoint","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"204":{"description":"Deleted"}}}},"/webhook_endpoints/{id}/resume":{"post":{"tags":["WebhookEndpoints"],"summary":"Un-pause a failing webhook endpoint","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"WebhookEndpoint","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookEndpoint"}}}},"422":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhook_deliveries":{"get":{"tags":["WebhookEndpoints"],"summary":"List webhookendpoints","security":[{"bearerAuth":[]}],"parameters":[{"name":"status","in":"query","required":false,"schema":{"type":"string"}},{"name":"event","in":"query","required":false,"schema":{"type":"string"}},{"name":"page","in":"query","required":false,"schema":{"type":"string"}},{"name":"per_page","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/WebhookDelivery"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}}}}},"/webhook_deliveries/{id}":{"get":{"tags":["WebhookEndpoints"],"summary":"Fetch webhookendpoint","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"WebhookDelivery","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebhookDelivery"}}}},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/webhook_deliveries/{id}/redeliver":{"post":{"tags":["WebhookEndpoints"],"summary":"Re-enqueue a webhook delivery (admin scope)","security":[{"bearerAuth":[]}],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"202":{"description":"Re-enqueued"},"404":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/me/rotate_key":{"post":{"tags":["Me"],"summary":"Rotate the current API key (admin scope). Old token stays valid for 24h.","security":[{"bearerAuth":[]}],"responses":{"201":{"description":"Rotated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RotateKeyResponse"}}}},"403":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/me/audit":{"get":{"tags":["Me"],"summary":"List API key audit events (90-day retention, admin scope)","security":[{"bearerAuth":[]}],"parameters":[{"name":"page","in":"query","required":false,"schema":{"type":"string"}},{"name":"per_page","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/ApiKeyAuditEvent"}},"meta":{"$ref":"#/components/schemas/PaginationMeta"}}}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Hibiki API key: hibiki_<prefix><secret>"}},"schemas":{"Error":{"type":"object","description":"Error envelope. `error_object` is canonical; the flat `error` string is kept as a sibling during the v1 deprecation window.","properties":{"error":{"type":"string","enum":["invalid_or_missing_api_key","insufficient_scope","not_found","bad_request","validation_failed","bad_state","rate_limited","unprocessable","webhook_signature_invalid"],"description":"Legacy flat error code (kept for backward compat)"},"error_object":{"$ref":"#/components/schemas/ErrorObject"},"retry_after":{"type":"integer","description":"Seconds until retry is permitted (rate_limited only)"},"required":{"type":"string","description":"Missing scope (insufficient_scope only)"}},"required":["error","error_object"]},"ErrorObject":{"type":"object","required":["code","message","request_id"],"properties":{"code":{"type":"string","enum":["invalid_or_missing_api_key","insufficient_scope","not_found","bad_request","validation_failed","bad_state","rate_limited","unprocessable","webhook_signature_invalid"]},"message":{"type":"string"},"request_id":{"type":"string","description":"Matches the X-Request-Id response header"},"detail":{"description":"String or array with additional context"},"fields":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string"}},"description":"Per-field validation errors (validation_failed only)"}}},"PaginationMeta":{"type":"object","properties":{"total":{"type":"integer"},"page":{"type":"integer"},"per_page":{"type":"integer"}}},"MeResponse":{"type":"object","properties":{"api_key":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"scope":{"type":"string"}}},"workspace":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"}}}}},"Contact":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"phone_number":{"type":"string"},"full_name":{"type":"string"},"email":{"type":"string"},"country_code":{"type":"string"},"locale":{"type":"string"},"opt_in_status":{"type":"string","enum":["pending","opted_in","opted_out"]},"opted_in_at":{"type":"string","format":"date-time"},"opt_in_source":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"custom_fields":{"type":"object","additionalProperties":true},"created_at":{"type":"string","format":"date-time"},"updated_at":{"type":"string","format":"date-time"}}},"ContactInput":{"type":"object","required":["phone_number"],"properties":{"phone_number":{"type":"string"},"full_name":{"type":"string"},"email":{"type":"string"},"country_code":{"type":"string"},"locale":{"type":"string"},"opt_in_status":{"type":"string","enum":["pending","opted_in","opted_out"]},"opt_in_source":{"type":"string"},"tags":{"type":"array","items":{"type":"string"}},"custom_fields":{"type":"object","additionalProperties":true}}},"ContactList":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"contacts_count":{"type":"integer"},"created_at":{"type":"string","format":"date-time"}}},"ContactListInput":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string"}}},"MembershipInput":{"type":"object","required":["contact_id"],"properties":{"contact_id":{"type":"string","format":"uuid"}}},"Membership":{"type":"object","properties":{"contact_list_id":{"type":"string","format":"uuid"},"contact_id":{"type":"string","format":"uuid"}}},"Tag":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"color":{"type":"string"},"taggings_count":{"type":"integer"}}},"TagInput":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"color":{"type":"string"}}},"Segment":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"description":{"type":"string"},"filter_rules":{"type":"object"},"contacts_count_cache":{"type":"integer"}}},"SegmentInput":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"description":{"type":"string"},"filter_rules":{"type":"object"}}},"Broadcast":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"status":{"type":"string"},"template":{"type":"string"},"language":{"type":"string"},"phone_number_id":{"type":"string","format":"uuid"},"whatsapp_flow_id":{"type":"string","format":"uuid"},"segment_id":{"type":"string","format":"uuid"},"contact_list_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"variable_mapping":{"type":"object"},"scheduled_at":{"type":"string","format":"date-time"},"counts":{"type":"object","properties":{"total":{"type":"integer"},"sent":{"type":"integer"},"delivered":{"type":"integer"},"read":{"type":"integer"},"failed":{"type":"integer"}}},"error_message":{"type":"string"}}},"BroadcastInput":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"message_template_id":{"type":"string","format":"uuid"},"whatsapp_flow_id":{"type":"string","format":"uuid"},"phone_number_id":{"type":"string","format":"uuid"},"segment_id":{"type":"string","format":"uuid"},"contact_list_ids":{"type":"array","items":{"type":"string","format":"uuid"}},"variable_mapping":{"type":"object"},"scheduled_at":{"type":"string","format":"date-time"}}},"Campaign":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"status":{"type":"string"},"objective":{"type":"string"},"provider":{"type":"string"},"currency":{"type":"string"},"budget_cents":{"type":"integer"},"start_date":{"type":"string","format":"date-time"},"end_date":{"type":"string","format":"date-time"},"targeting":{"type":"object"},"creative_spec":{"type":"object"},"meta":{"type":"object","properties":{"campaign_id":{"type":"string"},"adset_id":{"type":"string"},"ad_id":{"type":"string"}}},"stats":{"type":"object","properties":{"spend_cents":{"type":"integer"},"impressions":{"type":"integer"},"clicks":{"type":"integer"},"conversations_started":{"type":"integer"}}}}},"CampaignInput":{"type":"object","required":["name"],"properties":{"name":{"type":"string"},"objective":{"type":"string"},"currency":{"type":"string"},"budget_cents":{"type":"integer"},"start_date":{"type":"string","format":"date-time"},"end_date":{"type":"string","format":"date-time"},"targeting":{"type":"object"},"creative_spec":{"type":"object"}}},"Conversation":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string"},"contact_id":{"type":"string","format":"uuid"},"ad_campaign_id":{"type":"string","format":"uuid"},"ctwa_clid":{"type":"string"},"first_message_at":{"type":"string","format":"date-time"},"last_message_at":{"type":"string","format":"date-time"}}},"Message":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"conversation_id":{"type":"string","format":"uuid"},"contact_id":{"type":"string","format":"uuid"},"direction":{"type":"string","enum":["inbound","outbound"]},"content_type":{"type":"string"},"content":{"type":"string"},"status":{"type":"string"},"provider_message_id":{"type":"string"},"sent_at":{"type":"string","format":"date-time"},"delivered_at":{"type":"string","format":"date-time"},"read_at":{"type":"string","format":"date-time"},"error_message":{"type":"string"}}},"MessageInput":{"type":"object","required":["content"],"description":"Either conversation_id OR to_phone is required.","properties":{"conversation_id":{"type":"string","format":"uuid"},"to_phone":{"type":"string"},"contact_name":{"type":"string"},"content":{"type":"string"}}},"WebhookEndpoint":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"url":{"type":"string"},"description":{"type":"string"},"events":{"type":"array","items":{"type":"string","enum":["message.received","message.sent","message.delivered","message.read","message.failed","conversation.opened","conversation.resolved","conversation.converted","broadcast.completed","broadcast.failed"]}},"active":{"type":"boolean"},"failure_count":{"type":"integer"},"last_delivered_at":{"type":"string","format":"date-time"},"last_failed_at":{"type":"string","format":"date-time"},"paused_at":{"type":"string","format":"date-time"},"signing_secret":{"type":"string","description":"Only present in create/show. HMAC-SHA256 key for the X-Hibiki-Signature header on outbound deliveries."}}},"WebhookEndpointInput":{"type":"object","required":["url","events"],"properties":{"url":{"type":"string"},"description":{"type":"string"},"events":{"type":"array","items":{"type":"string","enum":["message.received","message.sent","message.delivered","message.read","message.failed","conversation.opened","conversation.resolved","conversation.converted","broadcast.completed","broadcast.failed"]}},"auth_header_name":{"type":"string"},"auth_header_value":{"type":"string"}}},"WebhookDelivery":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"event":{"type":"string","enum":["message.received","message.sent","message.delivered","message.read","message.failed","conversation.opened","conversation.resolved","conversation.converted","broadcast.completed","broadcast.failed"]},"delivery_id":{"type":"string","format":"uuid"},"attempt":{"type":"integer","description":"1-based attempt counter (capped at 5 retries)"},"success":{"type":"boolean"},"response_status":{"type":"integer"},"response_body_excerpt":{"type":"string","description":"First 8 KB of the response body"},"latency_ms":{"type":"integer"},"error_message":{"type":"string"},"next_retry_at":{"type":"string","format":"date-time"},"created_at":{"type":"string","format":"date-time"}}},"BatchContactsRequest":{"type":"object","required":["contacts"],"description":"Up to 500 contact records. Each entry is upserted on phone_number.","properties":{"contacts":{"type":"array","maxItems":500,"items":{"$ref":"#/components/schemas/ContactInput"}}}},"BatchTagsRequest":{"type":"object","required":["tags"],"description":"Up to 200 tags. Each entry is upserted on name.","properties":{"tags":{"type":"array","maxItems":200,"items":{"$ref":"#/components/schemas/TagInput"}}}},"BatchResult":{"type":"object","properties":{"data":{"type":"object","properties":{"created":{"type":"integer"},"updated":{"type":"integer"},"failed":{"type":"integer"},"errors":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"error":{"$ref":"#/components/schemas/ErrorObject"}}}}}},"meta":{"type":"object","properties":{"batch_id":{"type":"string","format":"uuid"}}}}},"ApiKeyAuditEvent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"api_key_id":{"type":"string","format":"uuid"},"event":{"type":"string","enum":["created","rotated","revoked","expired","auth_failed","scope_denied"]},"ip":{"type":"string"},"user_agent":{"type":"string"},"request_id":{"type":"string"},"metadata":{"type":"object","additionalProperties":true},"created_at":{"type":"string","format":"date-time"}}},"RotateKeyResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"token":{"type":"string","description":"Plaintext; shown once — store immediately"},"prefix":{"type":"string"},"scope":{"type":"string","enum":["read","write","admin"]},"expires_at":{"type":"string","format":"date-time"},"previous_revoked_at":{"type":"string","format":"date-time"}}}}}}},"x-webhook-events":["message.received","message.sent","message.delivered","message.read","message.failed","conversation.opened","conversation.resolved","conversation.converted","broadcast.completed","broadcast.failed"],"x-response-headers":{"X-Request-Id":"Per-request correlation id; echoed inside every error_object","X-RateLimit-Limit":"Requests allowed per minute for the authenticated key","X-RateLimit-Remaining":"Requests remaining in the current minute window","X-RateLimit-Reset":"Unix timestamp when the current minute window resets"}}