{"openapi":"3.1.0","info":{"title":"Agora REST (BYOK) API","version":"0.1.0","description":"Agora REST (BYOK) lets an AI assistant read your own Agora REST data through the Agora REST API with a key you supply (RESTful API customer ID). Read-only: 7 tools (list_projects, get_project, get_project_usage, list_conversational_agents, list_calls, get_call_statistics, get_usage_by_time). The BYOK key travels with each request, is used for that one call only and is never stored, logged or...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-agora-rest.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-agora-rest/docs"},"termsOfService":"https://connectorbay.com/byok-agora-rest/terms"},"servers":[{"url":"https://byok-agora-rest.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-agora-rest/docs"},"security":[{"upstreamKey":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."},"upstreamKey":{"type":"apiKey","in":"header","name":"X-Upstream-Key","description":"Your own key for the service this connector wraps (bring your own key). Used for that one call only; never stored, logged or cached."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/list_projects":{"post":{"operationId":"list_projects","summary":"List your Agora projects with project id, name, App ID (vendor_key), enabled status and creation time (app certificates ","description":"List your Agora projects with project id, name, App ID (vendor_key), enabled status and creation time (app certificates are not returned). Use for \"Which Agora projects do I have and what are their App IDs\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_projectsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_project":{"post":{"operationId":"get_project","summary":"Get one Agora project by id and name: App ID, enabled status and creation time (app certificate is not returned). Use fo","description":"Get one Agora project by id and name: App ID, enabled status and creation time (app certificate is not returned). Use for \"Show the details of one Agora project\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"id":{"description":"Project id from list_projects.","maxLength":64,"title":"Id","type":"string"},"name":{"description":"Project name from list_projects.","maxLength":255,"title":"Name","type":"string"}},"required":["id","name"],"title":"get_projectArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_project_usage":{"post":{"operationId":"get_project_usage","summary":"Get daily usage of one Agora project for a date range and business type (audio and video, transcoding, recording, cloud ","description":"Get daily usage of one Agora project for a date range and business type (audio and video, transcoding, recording, cloud recording or miniapp), in seconds by resolution. Use for \"How many Agora minutes did my project use last month\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"project_id":{"description":"Project id from list_projects.","maxLength":64,"title":"Project Id","type":"string"},"from_date":{"description":"Start date in UTC, for example 2026-01-01.","maxLength":10,"title":"From Date","type":"string"},"to_date":{"description":"End date in UTC, for example 2026-01-31.","maxLength":10,"title":"To Date","type":"string"},"business":{"description":"Business type to report.","enum":["default","transcodeDuration","recording","cloudRecording","miniapp"],"title":"Business","type":"string"}},"required":["project_id","from_date","to_date","business"],"title":"get_project_usageArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_conversational_agents":{"post":{"operationId":"list_conversational_agents","summary":"List Conversational AI agents of a project with id and state (IDLE, STARTING, RUNNING, STOPPING, STOPPED, FAILED), filte","description":"List Conversational AI agents of a project with id and state (IDLE, STARTING, RUNNING, STOPPING, STOPPED, FAILED), filtered by channel, time range or state. Use for \"Which Agora Conversational AI agents are running right now\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"app_id":{"description":"Agora App ID of the project.","maxLength":64,"title":"App Id","type":"string"},"channel":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"Only agents in this channel.","title":"Channel"},"from_time":{"anyOf":[{"maximum":4102444800,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"Start of the query range as Unix seconds (default 2 hours ago).","title":"From Time"},"to_time":{"anyOf":[{"maximum":4102444800,"minimum":0,"type":"integer"},{"type":"null"}],"default":null,"description":"End of the query range as Unix seconds (default now).","title":"To Time"},"state":{"anyOf":[{"maxLength":20,"type":"string"},{"type":"null"}],"default":null,"description":"Comma-separated agent states to include: 0 idle, 1 starting, 2 running, 3 stopping, 4 stopped, 6 failed (default 2).","title":"State"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Agents per page (default 20).","title":"Limit"},"cursor":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Cursor (meta.cursor) from the previous answer for the next page.","title":"Cursor"}},"required":["app_id"],"title":"list_conversational_agentsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/list_calls":{"post":{"operationId":"list_calls","summary":"List calls of a project in a time range with channel name, start and end time, peak and average callers and audio and vi","description":"List calls of a project in a time range with channel name, start and end time, peak and average callers and audio and video freeze rates (Call Inspector; needs an Agora Analytics plan). Use for \"Which Agora calls had quality problems yesterday\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"appid":{"description":"Agora App ID of the project (the vendor_key from list_projects).","maxLength":64,"title":"Appid","type":"string"},"start_ts":{"description":"Start of the range as Unix seconds (UTC).","maximum":4102444800,"minimum":0,"title":"Start Ts","type":"integer"},"end_ts":{"description":"End of the range as Unix seconds (UTC).","maximum":4102444800,"minimum":0,"title":"End Ts","type":"integer"},"cname":{"anyOf":[{"maxLength":64,"type":"string"},{"type":"null"}],"default":null,"description":"Only calls in this channel name.","title":"Cname"},"page_no":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page No"},"page_size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"Calls per page (default 20, maximum 100).","title":"Page Size"}},"required":["appid","start_ts","end_ts"],"title":"list_callsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_call_statistics":{"post":{"operationId":"get_call_statistics","summary":"Get audio or video freeze rate of one call broken down by country, region, network type, SDK version, operating system o","description":"Get audio or video freeze rate of one call broken down by country, region, network type, SDK version, operating system or device (Call Inspector; needs an Agora Analytics plan). Use for \"Which SDK versions had the worst audio freeze rate in this Agora call\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"appid":{"description":"Agora App ID of the project (the vendor_key from list_projects).","maxLength":64,"title":"Appid","type":"string"},"call_id":{"description":"Call id from list_calls.","maxLength":64,"title":"Call Id","type":"string"},"start_ts":{"description":"Start of the call as Unix seconds (UTC).","maximum":4102444800,"minimum":0,"title":"Start Ts","type":"integer"},"end_ts":{"description":"End of the call as Unix seconds (UTC).","maximum":4102444800,"minimum":0,"title":"End Ts","type":"integer"},"dimension":{"description":"Statistic dimension.","enum":["country","region","net","sdk","os","device"],"title":"Dimension","type":"string"},"metric":{"description":"Metric to compute.","enum":["audio_freeze_rate","video_freeze_rate"],"title":"Metric","type":"string"}},"required":["appid","call_id","start_ts","end_ts","dimension","metric"],"title":"get_call_statisticsArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/get_usage_by_time":{"post":{"operationId":"get_usage_by_time","summary":"Get a usage metric (users, sessions, channels, peak channels or users, durations) over a time range per hour or day (Dat","description":"Get a usage metric (users, sessions, channels, peak channels or users, durations) over a time range per hour or day (Data Insights; needs an Agora Analytics plan). Use for \"How many users joined my Agora channels each day last week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"appid":{"description":"Agora App ID of the project (the vendor_key from list_projects).","maxLength":64,"title":"Appid","type":"string"},"start_time":{"description":"Start of the range as Unix seconds (UTC).","maximum":4102444800,"minimum":0,"title":"Start Time","type":"integer"},"end_time":{"description":"End of the range as Unix seconds (UTC).","maximum":4102444800,"minimum":0,"title":"End Time","type":"integer"},"metric":{"description":"Usage metric to chart.","enum":["userCount","sessionCount","channelCount","peakCurrentChannels","peakCurrentUsers","totalDuration","totalVideoDuration"],"title":"Metric","type":"string"},"granularity":{"description":"Bucket size: 1d for days or 1h for hours.","enum":["1d","1h"],"title":"Granularity","type":"string"}},"required":["appid","start_time","end_time","metric","granularity"],"title":"get_usage_by_timeArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}