> This page is for version v2 (default). > For other versions, use one of these documentation indexes: > - v2 (default): https://docs.pinnacle.sh/v-2/llms.txt > - v1: https://docs.pinnacle.sh/v1/llms.txt > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.pinnacle.sh/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.pinnacle.sh/_mcp/server. # List Conferences GET https://api.pinnacle.sh/conferences Your team's conferences, newest first, each with its participants. Reference: https://docs.pinnacle.sh/api-reference/conferences/list-conferences ## Authentication - `PINNACLE-API-KEY` header (required) — API Key authentication via header ## Request ### Query parameters - `limit` (integer, optional, default: 25) - `status` (enum, optional) — - `waiting`: Created, but nobody has joined yet. - `active`: At least one participant has joined. - `ended`: Over. Every participant's call has been hung up. - Allowed values: `waiting`, `active`, `ended` ## Response ### 200 Conferences. - `data` (list of Conference, required) ## Errors ### 400 Bad Request Error Validation failed. The payload has missing required fields and/or invalid types. See [https://zod.dev/error-formatting](https://zod.dev/error-formatting) for more information. - `description` (string, required) — Human-readable summary of validation failures. - `errors` (ZodErrorErrors, required) — Structured dictionary of issues containing two main sections: - `errors`: Array of global validation errors not tied to specific fields - `properties`: Object mapping field names to their specific validation errors, where each field contains an `errors` array ### 401 Unauthorized Error The request lacks valid authentication credentials or the provided credentials are invalid. Ensure you're including a valid API key in the request headers and that your account has the necessary permissions to access this endpoint. - `error` (string, required) — Human-readable description of the error that occurred, corresponding to the HTTP status code. ### 500 Internal Server Error An unexpected error occurred on Pinnacle's servers while processing your request. If this error persists, please contact support with the request details. - `error` (string, required) — Human-readable description of the error that occurred, corresponding to the HTTP status code. ## Types ### Conference - `id` (string, required) - `label` (string, required, nullable) - `status` (enum, required) — - `waiting`: Created, but nobody has joined yet. - `active`: At least one participant has joined. - `ended`: Over. Every participant's call has been hung up. - Allowed values: `waiting`, `active`, `ended` - `participant_count` (integer, required) — Participants currently joined. - `max_participants` (integer, required) - `hold_audio_url` (string, required, nullable) — What participants on hold hear. - `speaking_events` (boolean, required) — Whether `participant.speaking` events are sent when the active speaker changes. - `metadata` (map from string to string, required) - `created_at` (string, required) - `started_at` (string, required, nullable) - `ended_at` (string, required, nullable) - `ended_reason` (enum, required, nullable) — Why a conference ended. A conference never ends just because one person is left. * `empty`: The last participant left. * `ended_by_api`: Ended with `DELETE /conferences/{id}` or the `conference.end` command. * `participant_ended_it`: A participant added with `end_conference_on_leave: true` left. * `time_limit`: Reached the 4-hour limit. * `expired_waiting`: Nobody joined in time. * `failed`: The conference couldn't be started. - Allowed values: `empty`, `ended_by_api`, `participant_ended_it`, `time_limit`, `expired_waiting`, `failed` - `participants` (list of Participant, required) ### ZodErrorErrors Structured dictionary of issues containing two main sections: - `errors`: Array of global validation errors not tied to specific fields - `properties`: Object mapping field names to their specific validation errors, where each field contains an `errors` array ### Participant A call in a conference. - `call_id` (string, required) — The participant is this call; every call API works on it. - `conference_id` (string, required) - `label` (string, required, nullable) - `status` (enum, required) — - `dialing`: A dialed participant whose call hasn't answered yet. - `ringing`: Answered and being connected (or hearing its `announce`). - `joined`: In the conference. - `left`: Hung up or was removed. - `failed`: Never connected (busy, no answer, rejected, or an error). - Allowed values: `dialing`, `ringing`, `joined`, `left`, `failed` - `from` (string, required, nullable) - `to` (string, required, nullable) - `muted` (boolean, required) — Nobody hears this participant; they still hear everyone. - `on_hold` (boolean, required) — They hear hold audio and nobody hears them. - `whisper_to` (list of string, required, nullable) — Call IDs of the only participants who can hear this one, or `null` for everyone. - `end_conference_on_leave` (boolean, required) — When this participant leaves, the conference ends for everyone. - `joined_at` (string, required, nullable) - `left_at` (string, required, nullable) - `left_reason` (enum, required, nullable) - Allowed values: `hangup`, `removed`, `busy`, `no_answer`, `rejected`, `failed`, `conference_ended` ## Examples **Response** ```json { "data": [ { "id": "conf_Hk2mX9pQ4rT7vB1nL8sW", "label": "escalation-4412", "status": "waiting", "participant_count": 1, "max_participants": 1, "hold_audio_url": "string", "speaking_events": true, "metadata": {}, "created_at": "2024-01-15T09:30:00Z", "started_at": "2024-01-15T09:30:00Z", "ended_at": "2024-01-15T09:30:00Z", "ended_reason": "empty", "participants": [ { "call_id": "call_7cQe4F8xT1yB2mN9pK3L", "conference_id": "conf_Hk2mX9pQ4rT7vB1nL8sW", "label": "supervisor", "status": "dialing", "from": "+14155559876", "to": "+14155551234", "muted": true, "on_hold": true, "whisper_to": [ "string" ], "end_conference_on_leave": true, "joined_at": "2024-01-15T09:30:00Z", "left_at": "2024-01-15T09:30:00Z", "left_reason": "hangup" } ] } ] } ``` **SDK Code** ```python import requests url = "https://api.pinnacle.sh/conferences" headers = {"PINNACLE-API-KEY": ""} response = requests.get(url, headers=headers) print(response.json()) ``` ```javascript const url = 'https://api.pinnacle.sh/conferences'; const options = {method: 'GET', headers: {'PINNACLE-API-KEY': ''}}; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.pinnacle.sh/conferences" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("PINNACLE-API-KEY", "") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.pinnacle.sh/conferences") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["PINNACLE-API-KEY"] = '' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.pinnacle.sh/conferences") .header("PINNACLE-API-KEY", "") .asString(); ``` ```php request('GET', 'https://api.pinnacle.sh/conferences', [ 'headers' => [ 'PINNACLE-API-KEY' => '', ], ]); echo $response->getBody(); ``` ```csharp using RestSharp; var client = new RestClient("https://api.pinnacle.sh/conferences"); var request = new RestRequest(Method.GET); request.AddHeader("PINNACLE-API-KEY", ""); IRestResponse response = client.Execute(request); ``` ```swift import Foundation let headers = ["PINNACLE-API-KEY": ""] let request = NSMutableURLRequest(url: NSURL(string: "https://api.pinnacle.sh/conferences")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```