diff --git a/docs/API Schema Documentation Enhancement.md b/docs/API Schema Documentation Enhancement.md new file mode 100644 index 0000000..3c2fe17 --- /dev/null +++ b/docs/API Schema Documentation Enhancement.md @@ -0,0 +1,68 @@ + +# API Schema Documentation + +This document provides detailed information about the request and response schemas for the jambonz API, focusing on the `/v1/Accounts/{account_sid}/Calls` and `/v1/Accounts/{account_sid}/Calls/{call_sid}` endpoints. Clear API documentation is crucial for successful integration and reduced development time. + +**Target Audience:** API developers, integration engineers + +**Status:** Complete + +## Request Schemas + +This section describes the schemas for requests made to the specified API endpoints. + +### `/v1/Accounts/{account_sid}/Calls` (POST) - Create a Call + +This endpoint allows you to initiate a new call. + +**Request Body Schema:** + +The request body should be a JSON object with the following properties: + +| Property | Type | Required | Description 0; + +**Example Request:** + +```json +{ + "from": "+15550000000", + "to": "+15550000001", + "answer_url": "https://example.com/answer", + "event_url": "https://example.com/events", + "event_method": "POST" +} +``` + +## Response Schemas + +This section describes the schemas for responses returned by the specified API endpoints. + +### `/v1/Accounts/{account_sid}/Calls` (POST) - Create a Call + +**Successful Response (201 Created):** + +| Property | Type | Description +| Property | Type | Description the call. It includes information such as the call's unique identifier (call_sid), the account associated with the call (account_sid), the phone numbers involved (from and to), and the current status of the call. +| `call_sid` | `string` | Unique identifier for the call. | +| `account_sid`| `string` | Account associated with the call. | +| `from` | `string` | Caller ID. | +| `to` | `string` | Callee number. | +| `status` | `string` | Current status of the call (e.g., `queued`, `ringing`, `in-progress`, `completed`). | + +**Example Response:** + +```json +{ + "call_sid": "CAxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", + "account_sid": "ACxxxxxxxxxxxxxxxxxxxxxxxxxxxxx", + "from": "+15550000000", + "to": "+15550000001", + "status": "queued" +} +``` + +### `/v1/Accounts/{account_sid}/Calls/{call_sid}` (GET) - Retrieve Call Details + +**Successful Response (200 OK):** + +| Property | Type | Description \ No newline at end of file