{"openapi":"3.1.0","info":{"title":"Jawbly API","version":"1.0.0","description":"Public API for the Jawbly platform: build AI assistants for WhatsApp into your own products and workflows."},"servers":[{"url":"https://api.jawbly.com/v1"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Per-business scoped API key."}}},"tags":[{"name":"Messages","description":"Send messages to your customers and read the conversation history, all provider-agnostic (WhatsApp today, more channels later)."},{"name":"Conversations","description":"The threads between your assistant and each customer, including handoff state so your own tools can take over."},{"name":"Contacts","description":"The people who message your business. Sync them into your CRM or enrich them from your own systems."},{"name":"Assistants","description":"Read and update the AI assistants that run your customer service, including their instructions and knowledge."},{"name":"Skills","description":"Skills are the programmable flows your assistant can run. Push definitions from your own tooling or CI."},{"name":"Catalog","description":"Everything you show customers: products, services, a menu. Sync your inventory in from your store."},{"name":"Records","description":"What your assistant collects from customers: orders, bookings and leads. Stream them into your fulfilment or sales tools."},{"name":"Analytics","description":"The numbers behind your assistant: conversations handled, resolution rate, leads captured."},{"name":"Usage & billing","description":"Read your token balance and metered usage so you can reconcile costs in your own systems."}],"paths":{"/messages":{"post":{"operationId":"messages-send","summary":"Send a message","description":"Send a text or template message from your connected number to a customer. Respects the channel’s 24-hour messaging window automatically.","tags":["Messages"],"security":[{"bearerAuth":["messages:write"]}],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"msg_2Zt9…","status":"queued","conversationId":"conv_8fA1…","createdAt":"2026-07-07T10:12:04Z"}}}}},"requestBody":{"content":{"application/json":{"example":{"to":"+14155550123","type":"text","text":"Your order #1024 is on its way 🚚"}}}}}},"/conversations/{conversationId}/messages":{"get":{"operationId":"messages-list","summary":"List messages","description":"Page through the messages in a conversation, newest first.","tags":["Messages"],"security":[{"bearerAuth":["messages:read"]}],"parameters":[{"name":"conversationId","in":"path","required":true,"description":"The conversation to read.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Page size. Defaults to 50.","schema":{"type":"string"}},{"name":"before","in":"query","required":false,"description":"Return messages older than this cursor.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"id":"msg_2Zt9…","direction":"outbound","text":"Your order #1024 is on its way 🚚","createdAt":"2026-07-07T10:12:04Z"}],"nextCursor":null}}}}}}},"/conversations":{"get":{"operationId":"conversations-list","summary":"List conversations","description":"List conversations for your business, filterable by status and assignee.","tags":["Conversations"],"security":[{"bearerAuth":["conversations:read"]}],"parameters":[{"name":"status","in":"query","required":false,"description":"Filter by conversation state.","schema":{"type":"string"}},{"name":"contactId","in":"query","required":false,"description":"Only conversations with this contact.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"id":"conv_8fA1…","contactId":"ct_5m…","status":"open","lastInboundAt":"2026-07-07T10:10:00Z"}],"nextCursor":null}}}}}}},"/conversations/{conversationId}/handoff":{"post":{"operationId":"conversations-handoff","summary":"Hand off to a human","description":"Pause the assistant on a conversation and mark it for a human agent, e.g. from your own inbox.","tags":["Conversations"],"security":[{"bearerAuth":["conversations:write"]}],"parameters":[{"name":"conversationId","in":"path","required":true,"description":"The conversation to hand off.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"conv_8fA1…","status":"handoff"}}}}}}},"/contacts":{"get":{"operationId":"contacts-list","summary":"List contacts","description":"Page through your contacts, filterable by tag or search term.","tags":["Contacts"],"security":[{"bearerAuth":["contacts:read"]}],"parameters":[{"name":"search","in":"query","required":false,"description":"Match on name or phone number.","schema":{"type":"string"}},{"name":"tag","in":"query","required":false,"description":"Filter by a contact tag.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"id":"ct_5m…","name":"Sara K.","phone":"+14155550123","tags":["vip"],"createdAt":"2026-06-30T09:00:00Z"}],"nextCursor":null}}}}}},"post":{"operationId":"contacts-upsert","summary":"Create or update a contact","description":"Upsert a contact by phone number, attaching your own metadata and tags.","tags":["Contacts"],"security":[{"bearerAuth":["contacts:write"]}],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"ct_5m…","phone":"+14155550123","name":"Sara K.","metadata":{"crmId":"A-2201"}}}}}},"requestBody":{"content":{"application/json":{"example":{"phone":"+14155550123","name":"Sara K.","metadata":{"crmId":"A-2201"}}}}}}},"/assistants/{assistantId}":{"get":{"operationId":"assistants-get","summary":"Get an assistant","description":"Fetch an assistant’s configuration, persona and attached knowledge.","tags":["Assistants"],"security":[{"bearerAuth":["assistants:read"]}],"parameters":[{"name":"assistantId","in":"path","required":true,"description":"The assistant to fetch.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"as_1k…","name":"Front desk","language":"auto","instructions":"You are the front desk for…","knowledgeItems":12}}}}}}},"/skills":{"get":{"operationId":"skills-list","summary":"List skills","description":"List the skills configured for an assistant.","tags":["Skills"],"security":[{"bearerAuth":["skills:read"]}],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"id":"sk_9d…","name":"Take order","enabled":true}],"nextCursor":null}}}}}}},"/skills/{skillId}":{"put":{"operationId":"skills-upsert","summary":"Upsert a skill","description":"Create or replace a skill definition (nodes + edges). Skills are stored data the engine interprets, so this is a plain JSON document.","tags":["Skills"],"security":[{"bearerAuth":["skills:write"]}],"parameters":[{"name":"skillId","in":"path","required":true,"description":"The skill to create or replace.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"id":"sk_9d…","name":"Take order","enabled":true}}}}},"requestBody":{"content":{"application/json":{"example":{"name":"Take order","enabled":true,"graph":{"nodes":[],"edges":[]}}}}}}},"/catalog/{collection}/items":{"post":{"operationId":"catalog-upsert","summary":"Upsert catalog items","description":"Bulk create or update items in a catalog collection. Ideal for keeping stock in sync with an external store.","tags":["Catalog"],"security":[{"bearerAuth":["catalog:write"]}],"parameters":[{"name":"collection","in":"path","required":true,"description":"The catalog collection, e.g. `products`.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"upserted":1,"collection":"products"}}}}},"requestBody":{"content":{"application/json":{"example":{"items":[{"externalId":"SKU-901","title":"Blue jacket","price":{"amount":4900,"currency":"USD"},"inStock":true}]}}}}}},"/records/{collection}":{"get":{"operationId":"records-list","summary":"List records","description":"Page through captured records for a collection, e.g. orders or leads.","tags":["Records"],"security":[{"bearerAuth":["records:read"]}],"parameters":[{"name":"collection","in":"path","required":true,"description":"The record collection, e.g. `orders`.","schema":{"type":"string"}},{"name":"since","in":"query","required":false,"description":"Only records created after this time.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"data":[{"id":"rec_44…","collection":"orders","fields":{"item":"Blue jacket","qty":1},"createdAt":"2026-07-07T10:14:00Z"}],"nextCursor":null}}}}}}},"/analytics/summary":{"get":{"operationId":"analytics-summary","summary":"Get analytics summary","description":"Aggregate metrics for a time window, matching what you see on the dashboard.","tags":["Analytics"],"security":[{"bearerAuth":["analytics:read"]}],"parameters":[{"name":"window","in":"query","required":false,"description":"Reporting window. Defaults to 30d.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"window":"30d","conversations":1840,"resolvedByAssistant":1622,"leads":213,"handoffs":218}}}}}}},"/usage/wallet":{"get":{"operationId":"usage-wallet","summary":"Get wallet balance","description":"Return the business’s current token balance and this period’s consumption.","tags":["Usage & billing"],"security":[{"bearerAuth":["usage:read"]}],"parameters":[],"responses":{"200":{"description":"Success","content":{"application/json":{"example":{"balanceTokens":184000,"periodUsedTokens":96000,"periodEndsAt":"2026-07-31T00:00:00Z"}}}}}}}}}