{"openapi":"3.1.0","info":{"title":"OpenAI Agents beta: agents, sessions, environments, vaults, webhooks (your key) API","version":"0.1.0","description":"OpenAI Agents beta: agents, sessions, environments, vaults, webhooks (your key) lets an AI assistant read your own OpenAI Agents data through the OpenAI Agents API with a key you supply (OpenAI API key). Read-only: 9 tools (list_agents, get_agent, list_agent_sessions, get_agent_session, list_session_artifacts, list_agent_environments, list_environment_templates, list_vaults,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-openai-agents.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-openai-agents/docs"},"termsOfService":"https://connectorbay.com/byok-openai-agents/terms"},"servers":[{"url":"https://byok-openai-agents.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-openai-agents/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_agents":{"post":{"operationId":"list_agents","summary":"List hosted agents with name, model, service tier and dates (instructions and tool definitions are not returned by this ","description":"List hosted agents with name, model, service tier and dates (instructions and tool definitions are not returned by this connector). Use for \"Which hosted agents have I created in OpenAI\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many items to return (1 to 100).","title":"Limit"},"order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":"desc","description":"Sort by creation time: asc or desc.","title":"Order"},"after":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Id of the last item of the previous page, to continue after it.","title":"After"}},"title":"list_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/get_agent":{"post":{"operationId":"get_agent","summary":"Get one hosted agent: name, model, service tier, metadata and dates (no instructions). Use for \"What model does my OpenA","description":"Get one hosted agent: name, model, service tier, metadata and dates (no instructions). Use for \"What model does my OpenAI agent agent_abc123 use\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"agent_id":{"description":"Agent id from list_agents.","maxLength":200,"title":"Agent Id","type":"string"}},"required":["agent_id"],"title":"get_agentArguments","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_agent_sessions":{"post":{"operationId":"list_agent_sessions","summary":"List agent sessions with status (idle, in_progress, requires_action, failed), error, last activity and token usage. Use ","description":"List agent sessions with status (idle, in_progress, requires_action, failed), error, last activity and token usage. Use for \"Which OpenAI agent sessions are waiting for action\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"agent_id":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only sessions whose root agent has this id.","title":"Agent Id"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many items to return (1 to 100).","title":"Limit"},"order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":"desc","description":"Sort by creation time: asc or desc.","title":"Order"},"after":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Id of the last item of the previous page, to continue after it.","title":"After"}},"title":"list_agent_sessionsArguments","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_agent_session":{"post":{"operationId":"get_agent_session","summary":"Get one agent session: status, error, last activity and token usage (no messages). Use for \"Did my OpenAI agent session ","description":"Get one agent session: status, error, last activity and token usage (no messages). Use for \"Did my OpenAI agent session fail\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"session_id":{"description":"Session id from list_agent_sessions.","maxLength":200,"title":"Session Id","type":"string"}},"required":["session_id"],"title":"get_agent_sessionArguments","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_session_artifacts":{"post":{"operationId":"list_session_artifacts","summary":"List the artifacts (files) an agent session produced with path, size and the turn that created them (content is not read","description":"List the artifacts (files) an agent session produced with path, size and the turn that created them (content is not read). Use for \"What files did my OpenAI agent session produce\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"session_id":{"description":"Session id from list_agent_sessions.","maxLength":200,"title":"Session Id","type":"string"},"environment_id":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only artifacts produced by this environment id.","title":"Environment Id"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many items to return (1 to 100).","title":"Limit"},"order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":"desc","description":"Sort by creation time: asc or desc.","title":"Order"},"after":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Id of the last item of the previous page, to continue after it.","title":"After"}},"required":["session_id"],"title":"list_session_artifactsArguments","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_agent_environments":{"post":{"operationId":"list_agent_environments","summary":"List hosted environments agents run in with status and type (files, plugins and skills attached are not expanded). Use f","description":"List hosted environments agents run in with status and type (files, plugins and skills attached are not expanded). Use for \"Which environments are available to my OpenAI agents\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"type":{"anyOf":[{"const":"openai_hosted","type":"string"},{"type":"null"}],"default":"openai_hosted","description":"Hosting type to list.","title":"Type"},"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many items to return (1 to 100).","title":"Limit"},"order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":"desc","description":"Sort by creation time: asc or desc.","title":"Order"},"after":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Id of the last item of the previous page, to continue after it.","title":"After"}},"title":"list_agent_environmentsArguments","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_environment_templates":{"post":{"operationId":"list_environment_templates","summary":"List environment templates (reusable environment setups) with name, capability directories and dates. Use for \"What envi","description":"List environment templates (reusable environment setups) with name, capability directories and dates. Use for \"What environment templates exist for my OpenAI agents\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many items to return (1 to 100).","title":"Limit"},"order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":"desc","description":"Sort by creation time: asc or desc.","title":"Order"},"after":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Id of the last item of the previous page, to continue after it.","title":"After"}},"title":"list_environment_templatesArguments","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_vaults":{"post":{"operationId":"list_vaults","summary":"List credential vaults agents can use (name and dates only; credentials are not read). Use for \"Which credential vaults ","description":"List credential vaults agents can use (name and dates only; credentials are not read). Use for \"Which credential vaults exist in my OpenAI project\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many items to return (1 to 100).","title":"Limit"},"order":{"anyOf":[{"enum":["asc","desc"],"type":"string"},{"type":"null"}],"default":"desc","description":"Sort by creation time: asc or desc.","title":"Order"},"after":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Id of the last item of the previous page, to continue after it.","title":"After"}},"title":"list_vaultsArguments","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_webhook_endpoints":{"post":{"operationId":"list_webhook_endpoints","summary":"List the project's webhook endpoints with name, URL, subscribed event types and a masked hint of the signing secret. Use","description":"List the project's webhook endpoints with name, URL, subscribed event types and a masked hint of the signing secret. Use for \"Which webhook endpoints are configured in my OpenAI project\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"limit":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many items to return (1 to 100).","title":"Limit"},"after":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Id of the last item of the previous page, to continue after it.","title":"After"}},"title":"list_webhook_endpointsArguments","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}}}}