{"openapi":"3.1.0","info":{"title":"CosVoice API","version":"1.0.0","summary":"Give an AI assistant a real phone number and email address.","description":"A CosVoice line is one phone number and one email address belonging to one assistant. Ask it to call someone in plain English; it holds the conversation, then writes up what happened. Calls take minutes: place a call, then poll GET /calls/{id} or wait for the call.completed webhook. Get a key at https://cosvoice.com/desk/settings (Connect your agent). Send it as an Authorization: Bearer header. Rate limit: 240 requests a minute per key.","contact":{"name":"CosVoice","url":"https://cosvoice.com/contact"},"termsOfService":"https://cosvoice.com/terms"},"servers":[{"url":"https://cosvoice.com/api/v1"}],"security":[{"bearerAuth":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"A line's API key (cv_live_…), from Settings → Connect your agent."}},"schemas":{"Call":{"type":"object","properties":{"id":{"type":"string","description":"Call id."},"direction":{"type":"string","enum":["inbound","outbound"]},"status":{"type":"string","enum":["queued","ringing","in-progress","completed","no-answer","busy","failed"]},"to":{"type":"string","description":"The other party, E.164."},"from":{"type":"string","description":"The line's number, E.164."},"outcome":{"type":"string","description":"One line: what happened.","example":"Reserved · Friday 8:15pm · party of 2"},"summary":{"type":"string","description":"A short written account of the call."},"action_items":{"type":"array","items":{"type":"string"}},"notes":{"type":"object","additionalProperties":true,"description":"Details the line captured: names, amounts, dates, reference numbers."},"transcript":{"type":"array","items":{"type":"object","properties":{"role":{"type":"string","enum":["assistant","caller"]},"text":{"type":"string"},"at":{"type":"string","format":"date-time"}}}},"duration_seconds":{"type":"integer"},"created_at":{"type":"string","format":"date-time"}}},"Error":{"type":"object","properties":{"error":{"type":"string","description":"What went wrong, in plain words you can show the owner."}},"required":["error"]}},"responses":{"BadRequest":{"description":"Something in the request is missing or malformed; the message says which field.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"Unauthorized":{"description":"The key is missing, wrong, or revoked. Ask the owner for a new one; do not retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFound":{"description":"No such call, email, or contact on this line.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"RateLimited":{"description":"Over 240 requests a minute. Wait a little and try again.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/line":{"get":{"operationId":"getLine","summary":"The line's number, email, name, and minutes left.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The line.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/calls":{"get":{"operationId":"listCalls","summary":"Recent calls, newest first.","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":20,"maximum":100}}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Recent calls.","content":{"application/json":{"schema":{"type":"object","properties":{"calls":{"type":"array","items":{"$ref":"#/components/schemas/Call"}}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"placeCall","summary":"Call someone on the owner's behalf.","description":"Say what you would tell a person, including what to accept if the first answer is no. Returns straight away with a call id; the call itself takes minutes.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["to","purpose"],"properties":{"to":{"type":"string","description":"Who to call, E.164.","example":"+13105550142"},"purpose":{"type":"string","description":"The job, in plain English, including fallbacks.","example":"Book a table for two this Friday at 7:30 under Graham. If 7:30 is gone, take anything between 7:00 and 8:30."},"callee_name":{"type":"string","description":"Who is being called.","example":"Osteria Mozza, host stand"},"desired_resolution":{"type":"string","description":"What a good ending looks like.","example":"A confirmed reservation with a time."},"max_minutes":{"type":"integer","description":"Hard stop for the call.","default":10}}}}}},"responses":{"200":{"description":"The call was placed.","content":{"application/json":{"schema":{"type":"object","properties":{"call":{"$ref":"#/components/schemas/Call"}}}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/calls/{id}":{"get":{"operationId":"getCall","summary":"How a call went: outcome, notes, transcript.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The call.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Call"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/calls/{id}/annotations":{"post":{"operationId":"annotateCall","summary":"Leave a note on a call for the owner.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["note"],"properties":{"note":{"type":"string","description":"What to record."}}}}}},"responses":{"200":{"description":"Saved.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/reservations":{"get":{"operationId":"listReservations","summary":"Tables the line has booked.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Reservations.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"bookReservation","summary":"Book a table by phone.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["venue_phone","party_size","requested_for"],"properties":{"venue_name":{"type":"string","description":"Restaurant name."},"venue_phone":{"type":"string","description":"Restaurant number, E.164."},"party_size":{"type":"integer"},"requested_for":{"type":"string","description":"When, in plain words or ISO.","example":"Friday 7:30pm"},"fallbacks":{"type":"string","description":"What else is acceptable.","example":"7:00 to 8:30"}}}}}},"responses":{"200":{"description":"Placed.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/messages":{"get":{"operationId":"listMessages","summary":"Texts to and from the line.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Messages.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"sendText","summary":"Send a text from the line's number.","description":"US carriers only deliver business texts from registered numbers; CosVoice's registration is in progress, so a text may be filtered. Use a call or email when it must arrive.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["to","body"],"properties":{"to":{"type":"string","description":"E.164."},"body":{"type":"string","description":"The message."}}}}}},"responses":{"200":{"description":"Handed to the carrier.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/emails":{"get":{"operationId":"listEmails","summary":"Mail that reached the line.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Emails.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/emails/{id}":{"get":{"operationId":"getEmail","summary":"One message.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"The email.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/emails/{id}/forward":{"post":{"operationId":"forwardEmail","summary":"Send a message on to an inbox.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["to"],"properties":{"to":{"type":"string","description":"Where to send it."},"note":{"type":"string","description":"A line of context."}}}}}},"responses":{"200":{"description":"Sent.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/contacts":{"get":{"operationId":"listContacts","summary":"Who the line knows.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Contacts.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"post":{"operationId":"addContact","summary":"Teach the line a number and how to treat it.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name","phone"],"properties":{"name":{"type":"string","description":"Their name."},"phone":{"type":"string","description":"E.164."},"role":{"type":"string","enum":["approved","vip","blocked"]},"notes":{"type":"string","description":"Anything the line should know."}}}}}},"responses":{"200":{"description":"Saved.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/contacts/{phone}":{"delete":{"operationId":"removeContact","summary":"Forget a number.","parameters":[{"name":"phone","in":"path","required":true,"schema":{"type":"string"}}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Removed.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/settings":{"get":{"operationId":"getSettings","summary":"Name, voice, greeting, standing instructions.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Settings.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}},"patch":{"operationId":"updateSettings","summary":"Change the line's name, voice, greeting, instructions, or when it answers.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"properties":{"name":{"type":"string","description":"What the line calls itself."},"voice":{"type":"string","description":"A voice id."},"greeting":{"type":"string","description":"First line on inbound calls."},"instructions":{"type":"string","description":"What the line should always know."},"answer_rings":{"type":"integer"}}}}}},"responses":{"200":{"description":"Saved.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/activity":{"get":{"operationId":"recentActivity","summary":"Calls, texts, and mail since a timestamp. Use it to catch up.","parameters":[{"name":"since","in":"query","schema":{"type":"string","format":"date-time"}}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Everything since then.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/history":{"get":{"operationId":"listHistory","summary":"The whole history, as JSON or CSV.","parameters":[{"name":"format","in":"query","schema":{"type":"string","enum":["json","csv"]}},{"name":"type","in":"query","schema":{"type":"string","enum":["all","call","message","email"]}}],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"History.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/webhook":{"post":{"operationId":"setWebhook","summary":"Where to post call.started, call.completed, message.received, email.received.","security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","description":"Your HTTPS endpoint."}}}}}},"responses":{"200":{"description":"Saved.","content":{"application/json":{"schema":{"type":"object"}}}},"400":{"$ref":"#/components/responses/BadRequest"},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"},"429":{"$ref":"#/components/responses/RateLimited"}}}}}}