{"openapi":"3.1.0","info":{"title":"Guava API Server","version":"guava-release-0.51.0"},"servers":[{"url":"https://app.goguava.ai"}],"paths":{"/v1/sms/messages":{"get":{"tags":["SMS"],"summary":"List received SMS messages","description":"Lists SMS messages received on one of your organization's numbers, oldest first.\n\nResults are paginated. If `next_url` is non-null, send a GET request to it (with the same credentials) to fetch the\nnext page. When `next_url` is null, you've reached the most recent message.","operationId":"api_list_sms_messages_v1_sms_messages_get","security":[{"APIKey":[]}],"parameters":[{"name":"to_number","in":"query","required":true,"schema":{"type":"string","pattern":"^\\+[1-9]\\d{1,14}$","description":"Your organization's number to list received messages for, in E.164 format.","examples":["+14155550100"],"title":"To Number"},"description":"Your organization's number to list received messages for, in E.164 format."},{"name":"received_after","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Only return messages received strictly after this time, as an ISO 8601 timestamp. Timestamps without an offset are treated as UTC. Defaults to returning all messages.","examples":["2026-10-19T17:00:00Z"],"title":"Received After"},"description":"Only return messages received strictly after this time, as an ISO 8601 timestamp. Timestamps without an offset are treated as UTC. Defaults to returning all messages."},{"name":"from_number","in":"query","required":false,"schema":{"anyOf":[{"type":"string","pattern":"^\\+[1-9]\\d{1,14}$"},{"type":"null"}],"description":"Only return messages from this sender, in E.164 format.","examples":["+14155550123"],"title":"From Number"},"description":"Only return messages from this sender, in E.164 format."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Maximum number of messages per page.","default":50,"title":"Limit"},"description":"Maximum number of messages per page."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SMSMessagePage"}}}},"401":{"description":"Missing or invalid credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Your account has an unresolved billing issue."},"404":{"description":"`to_number` isn't owned by your organization.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/conversations/{call_id}/metadata":{"put":{"tags":["Calls"],"summary":"Set conversation custom metadata","description":"Stores a custom JSON object on a conversation, replacing any existing metadata, and returns the stored metadata.\nThe object is also returned as `metadata` when fetching the conversation. The serialized object may be at\nmost 4 KiB, and objects and arrays may be nested at most 5 levels deep.","operationId":"api_put_conversation_user_metadata_v1_conversations__call_id__metadata_put","security":[{"APIKey":[]}],"parameters":[{"name":"call_id","in":"path","required":true,"schema":{"type":"string","description":"ID of the call to attach metadata to.","title":"Call Id"},"description":"ID of the call to attach metadata to."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"An arbitrary JSON object.","title":"Metadata"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserMetadataResponse"}}}},"400":{"description":"Metadata is nested more than 5 levels deep, or contains NaN or Infinity.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Conversation not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Metadata exceeds 4 KiB when serialized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"patch":{"tags":["Calls"],"summary":"Update conversation custom metadata","description":"Applies a [JSON merge patch](https://www.rfc-editor.org/rfc/rfc7396) to a conversation's custom metadata and\nreturns the resulting metadata. Keys set to `null` are removed, nested objects are merged recursively, and all\nother values replace the existing value. If the conversation has no metadata, the patch is applied to an empty\nobject. The result has the same size and depth limits as PUT.","operationId":"api_patch_conversation_user_metadata_v1_conversations__call_id__metadata_patch","security":[{"APIKey":[]}],"parameters":[{"name":"call_id","in":"path","required":true,"schema":{"type":"string","description":"ID of the call whose metadata to update.","title":"Call Id"},"description":"ID of the call whose metadata to update."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"A JSON merge patch (RFC 7396) object.","title":"Patch"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserMetadataResponse"}}}},"400":{"description":"Metadata is nested more than 5 levels deep, or contains NaN or Infinity.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Conversation not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"413":{"description":"Metadata exceeds 4 KiB when serialized.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/webrtc/codes":{"post":{"tags":["WebRTC"],"summary":"Create WebRTC agent routing code","description":"Creates a code that lets WebRTC clients connect to your agent.","operationId":"create_webrtc_agent_v1_webrtc_codes_post","security":[{"APIKey":[]}],"parameters":[{"name":"expires_in","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":1},{"type":"null"}],"description":"Lifetime of the code in seconds. If omitted, the code never expires.","title":"Expires In"},"description":"Lifetime of the code in seconds. If omitted, the code never expires."},{"name":"label","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Human-readable label for the code.","title":"Label"},"description":"Human-readable label for the code."},{"name":"require_token","in":"query","required":false,"schema":{"type":"boolean","description":"If true, clients must present a token to connect, not just the code.","default":false,"title":"Require Token"},"description":"If true, clients must present a token to connect, not just the code."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebRTCAgentCodeResponse"}}}},"401":{"description":"Missing or invalid credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/webrtc/client-tokens":{"post":{"tags":["WebRTC"],"summary":"Create WebRTC client token","description":"Creates a short-lived token that lets a client connect to a WebRTC code.\n\nTokens are single-use: a token is consumed when a call is created with it. Create a new\ntoken for each call.","operationId":"create_webrtc_client_token_v1_webrtc_client_tokens_post","security":[{"APIKey":[]}],"parameters":[{"name":"webrtc_code","in":"query","required":true,"schema":{"type":"string","description":"The WebRTC code the token grants access to.","title":"Webrtc Code"},"description":"The WebRTC code the token grants access to."},{"name":"expires_in","in":"query","required":false,"schema":{"type":"integer","maximum":86400,"minimum":1,"description":"Seconds until the token expires if it isn't used.","default":3600,"title":"Expires In"},"description":"Seconds until the token expires if it isn't used."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WebRTCClientTokenResponse"}}}},"401":{"description":"Missing or invalid credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"WebRTC code not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/conversations/{call_id}":{"delete":{"tags":["Calls"],"summary":"Delete conversation","description":"Deletes a conversation, including its transcript and recordings.","operationId":"api_delete_conversation_v1_conversations__call_id__delete","security":[{"APIKey":[]}],"parameters":[{"name":"call_id","in":"path","required":true,"schema":{"type":"string","description":"ID of the call to delete.","title":"Call Id"},"description":"ID of the call to delete."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OkResponse"}}}},"401":{"description":"Missing or invalid credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Conversation not found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/deprecation-status":{"get":{"summary":"Check component deprecation","description":"Checks whether a given version of a Guava component is still supported.","operationId":"check_component_deprecation_v1_deprecation_status_get","parameters":[{"name":"component","in":"query","required":true,"schema":{"type":"string","description":"Component name.","examples":["python-sdk"],"title":"Component"},"description":"Component name."},{"name":"version","in":"query","required":true,"schema":{"type":"string","description":"Component version.","examples":["0.23.0"],"title":"Version"},"description":"Component version."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DeprecationStatusResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/sms/send":{"post":{"tags":["SMS"],"summary":"Send SMS","description":"Sends an SMS from one of your organization's phone numbers.","operationId":"send_sms_v1_sms_send_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendSMSRequest"}}},"required":true},"responses":{"201":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SendSMSResponse"}}}},"400":{"description":"The sender number isn't owned by your organization or isn't SMS-enabled.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Missing or invalid credentials.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Your account has an unresolved billing issue."},"500":{"description":"The carrier failed to send the message.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"APIKey":[]}]}}},"components":{"schemas":{"DeprecationStatusResponse":{"properties":{"deprecation_status":{"type":"string","enum":["supported","deprecated","unknown"],"title":"Deprecation Status","description":"`unknown` if the component isn't recognized."}},"type":"object","required":["deprecation_status"],"title":"DeprecationStatusResponse"},"ErrorResponse":{"properties":{"detail":{"type":"string","title":"Detail"}},"type":"object","required":["detail"],"title":"ErrorResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"OkResponse":{"properties":{"ok":{"type":"boolean","const":true,"title":"Ok","default":true}},"type":"object","title":"OkResponse"},"SMSMessage":{"properties":{"id":{"type":"string","title":"Id","description":"Unique ID of the message.","examples":["6710a3f2c1e4b5a6d7e8f901"]},"from_number":{"type":"string","title":"From Number","description":"Sender, in E.164 format.","examples":["+14155550123"]},"to_number":{"type":"string","title":"To Number","description":"Your organization's number that received the message, in E.164 format.","examples":["+14155550100"]},"content":{"type":"string","title":"Content","description":"Message body.","examples":["Yes, 3pm works for me."]},"received_at":{"type":"string","format":"date-time","title":"Received At","description":"When Guava received the message, in UTC."},"direction":{"type":"string","title":"Direction","description":"Always `inbound`.","examples":["inbound"]}},"type":"object","required":["id","from_number","to_number","content","received_at","direction"],"title":"SMSMessage","description":"An inbound SMS message received on one of your organization's numbers."},"SMSMessagePage":{"properties":{"results":{"items":{"$ref":"#/components/schemas/SMSMessage"},"type":"array","title":"Results","description":"Results on this page."},"next_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Url","description":"URL of the next page of results, or null if this is the last page. Send a GET request to it as-is."}},"type":"object","required":["results"],"title":"SMSMessagePage"},"SendSMSRequest":{"properties":{"from_number":{"type":"string","pattern":"^\\+[1-9]\\d{1,14}$","title":"From Number","description":"Sender, in E.164 format. Must be an SMS-enabled number owned by your organization.","examples":["+14155550100"]},"to_number":{"type":"string","pattern":"^\\+[1-9]\\d{1,14}$","title":"To Number","description":"Recipient, in E.164 format.","examples":["+14155550123"]},"message":{"type":"string","title":"Message","description":"Message body.","examples":["Your appointment is confirmed for 3pm tomorrow."]}},"type":"object","required":["from_number","to_number","message"],"title":"SendSMSRequest"},"SendSMSResponse":{"properties":{"status":{"type":"string","title":"Status","description":"Delivery status reported by the carrier, e.g. `queued` or `sent`."}},"type":"object","required":["status"],"title":"SendSMSResponse"},"UserMetadataResponse":{"properties":{"metadata":{"additionalProperties":true,"type":"object","title":"Metadata"}},"type":"object","required":["metadata"],"title":"UserMetadataResponse"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"},"WebRTCAgentCodeResponse":{"properties":{"webrtc_code":{"type":"string","title":"Webrtc Code"},"label":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Label"},"require_token":{"type":"boolean","title":"Require Token"},"created_at":{"type":"string","format":"date-time","title":"Created At"},"expires_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Expires At"}},"type":"object","required":["webrtc_code","label","require_token","created_at","expires_at"],"title":"WebRTCAgentCodeResponse"},"WebRTCClientTokenResponse":{"properties":{"token":{"type":"string","title":"Token"},"expires_at":{"type":"string","format":"date-time","title":"Expires At"}},"type":"object","required":["token","expires_at"],"title":"WebRTCClientTokenResponse"}},"securitySchemes":{"APIKey":{"type":"http","description":"A Guava API key, sent as `Authorization: Bearer <key>`.","scheme":"bearer"}}}}