{"openapi":"3.0.0","info":{"title":"Agent API V1","version":"1.0","contact":{"name":"ZoomInfo Customer Support","email":"help@zoominfo.com"},"description":"This definition only exposes one of many API routes from agentic-ai-platform\n    in order to quickly support an integration opportunity with SalesForce.\n    The model includes some definitions used by API routes that are not being\n    surfaced at this time. They remain included where they are referenced as\n    dependencies, to avoid model refactoring, and with the intent that additional\n    capabilities of agentic-ai-platform will be released under ZI-API in the future/"},"tags":[{"name":"Agents"}],"paths":{"/agent/v1/agents":{"get":{"operationId":"AgentsController_listAgents","summary":"List Agents","description":"Lists all agents available to your tenant, including ZoomInfo managed agents\nand your tenant's published Agent Teams. Before running an agent, use\n[Get Agent Details](ref:agentscontroller_getagent) to review its required\ninputs and supported capabilities.\n\nPer [Credit Usage and Limits](doc:credit-usage-and-limits), this endpoint\ndoes not consume credits.","parameters":[{"name":"filter[name]","in":"query","required":false,"description":"Filter agents by name (case-insensitive substring match).","schema":{"type":"string"},"explode":false},{"name":"filter[tags]","in":"query","required":false,"description":"Filter agents by tag name, as a comma-separated list (e.g. `sales,enrichment`). Returns agents carrying at least one of the given tags.","schema":{"type":"string"},"explode":false},{"name":"filter[managedBy]","in":"query","required":false,"description":"Filter agents by operator.","schema":{"$ref":"#/components/schemas/AgentManagedBy"},"explode":false},{"name":"filter[executionMode]","in":"query","required":false,"description":"Filter agents by supported execution mode.","schema":{"$ref":"#/components/schemas/AgentExecutionMode"},"explode":false},{"name":"page[size]","in":"query","required":false,"description":"The number of agents to return per page. Allowable values are between 1 and 100. Defaults to 25.","schema":{"type":"integer","format":"int32","minimum":1,"maximum":100},"explode":false},{"name":"page[after]","in":"query","required":false,"description":"Opaque cursor from the previous page's `links.next`. Omit to fetch the first page.","schema":{"type":"string"},"explode":false}],"responses":{"200":{"description":"Success","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/AgentsListResponse"}}}},"400":{"description":"Bad Request","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ZoomInfo.Core.Foundations.ErrorResponseModel"}}}},"401":{"description":"Unauthorized","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ZoomInfo.Core.Foundations.ErrorResponseModel"}}}},"403":{"description":"Forbidden","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ZoomInfo.Core.Foundations.ErrorResponseModel"}}}},"429":{"description":"Too Many Requests","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ZoomInfo.Core.Foundations.ErrorResponseModel"}}}}},"tags":["Agents"],"security":[{"OAuth2Auth":["api:agent:read"]}],"x-api-roles":["fea:pls"]}},"/agent/v1/agents/{agentId}":{"get":{"operationId":"AgentsController_getAgent","summary":"Get Agent Details","description":"Retrieves the full details for a specific agent, including the inputs\nrequired to run it. Call this endpoint before starting a run. The expected\ninput is defined in `inputSchema`, which describes the message parts the\nagent accepts, such as `text` or structured `data`, and whether each part is\nrequired.\n\nFor structured input, the `schema` defines the payload that must be provided\nin the corresponding `data` part of\n[Start Agent Run](ref:agentscontroller_startagentrun). `inputSchema` is\nreturned only by this endpoint and is not included in\n[List Agents](ref:agentscontroller_listagents). It is omitted when the agent\ndoes not define an input contract.","parameters":[{"name":"agentId","in":"path","required":true,"description":"The unique identifier of the agent.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/AgentDetailResponse"}}}},"401":{"description":"Unauthorized","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ZoomInfo.Core.Foundations.ErrorResponseModel"}}}},"403":{"description":"Forbidden","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ZoomInfo.Core.Foundations.ErrorResponseModel"}}}},"404":{"description":"Not Found","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ZoomInfo.Core.Foundations.ErrorResponseModel"}}}},"429":{"description":"Too Many Requests","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ZoomInfo.Core.Foundations.ErrorResponseModel"}}}}},"tags":["Agents"],"security":[{"OAuth2Auth":["api:agent:read"]}],"x-api-roles":["fea:pls"]}},"/agent/v1/agents/{agentId}/runs":{"post":{"operationId":"AgentsController_startAgentRun","summary":"Start Agent Run","description":"Starts a new run for the specified agent.\n\nBy default, agent runs are asynchronous. The request returns the in-progress\nrun, including its run id in `data.id`, while execution continues in the\nbackground. Use that run id with\n[Get Agent Run](ref:agentscontroller_getagentrun) to retrieve the latest\nstatus and final result.\n\nTo run the agent synchronously, set `returnImmediately: false` in\n`data.attributes`. The connection remains open while the agent executes, up\nto a maximum of 300 seconds. If the run does not complete within that\nwindow, the response returns the in-progress run and execution continues in\nthe background. Use the returned run id from `data.id` with\n[Get Agent Run](ref:agentscontroller_getagentrun) to retrieve the latest\nstatus and final result.\n\nWhen the run completes, the first item in `artifacts` contains the primary\nresponse and may include text and structured data. Additional artifacts,\nwhen present, contain supplementary output.\n\nThe request message is validated against the agent's `inputSchema`. Use\n[Get Agent Details](ref:agentscontroller_getagent) before starting a run to\nreview the required input format.","parameters":[{"name":"agentId","in":"path","required":true,"description":"The unique identifier of the agent to run.","schema":{"type":"string"}}],"responses":{"200":{"description":"Success","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/AgentRunResponse"}}}},"400":{"description":"Bad Request","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ZoomInfo.Core.Foundations.ErrorResponseModel"}}}},"401":{"description":"Unauthorized","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ZoomInfo.Core.Foundations.ErrorResponseModel"}}}},"403":{"description":"Forbidden","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ZoomInfo.Core.Foundations.ErrorResponseModel"}}}},"404":{"description":"Not Found","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ZoomInfo.Core.Foundations.ErrorResponseModel"}}}},"409":{"description":"Conflict","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ZoomInfo.Core.Foundations.ErrorResponseModel"}}}},"429":{"description":"Too Many Requests","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ZoomInfo.Core.Foundations.ErrorResponseModel"}}}}},"tags":["Agents"],"requestBody":{"required":true,"content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/StartAgentRunRequestBody"}}},"description":"The run request. The sync/async switch `returnImmediately` is a field of `data.attributes`, not a query parameter (A2A carries it in the message body)."},"security":[{"OAuth2Auth":["api:agent:execute"]}],"x-additional-content-types":["application/json"],"x-api-roles":["fea:pls"]},"get":{"operationId":"AgentsController_listAgentRuns","summary":"List Agent Runs","description":"Lists the run history for a specific agent, with the most recent runs\nreturned first.\nUse this endpoint to review previous and active runs for the agent. To\nretrieve the current status and results of a specific run, use\n[Get Agent Run](ref:agentscontroller_getagentrun) instead.\nThis endpoint does not start or modify a run.","parameters":[{"name":"agentId","in":"path","required":true,"description":"The unique identifier of the agent.","schema":{"type":"string"}},{"name":"filter[status]","in":"query","required":false,"description":"Filter runs by one or more task states (comma-delimited).","schema":{"type":"array","items":{"$ref":"#/components/schemas/AgentTaskState"}},"explode":false},{"name":"filter[createdAt]","in":"query","required":false,"description":"Filter runs by creation time: an ISO 8601 timestamp, or the range form `[timestamp,*)` for on-or-after.","schema":{"type":"string"},"explode":false},{"name":"filter[initiatedBy]","in":"query","required":false,"description":"Filter runs by the initiating user, workflow, or API client identifier.","schema":{"type":"string"},"explode":false},{"name":"sort","in":"query","required":false,"description":"Sort order. Only the default `-createdAt` (newest first) is supported; other values are rejected.","schema":{"type":"string"},"explode":false},{"name":"page[size]","in":"query","required":false,"description":"The number of runs to return per page. Allowable values are between 1 and 100. Defaults to 25.","schema":{"type":"integer","format":"int32","minimum":1,"maximum":100},"explode":false},{"name":"page[after]","in":"query","required":false,"description":"Opaque cursor from the previous page's `links.next`. Omit to fetch the first page.","schema":{"type":"string"},"explode":false}],"responses":{"200":{"description":"Success","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/AgentRunsListResponse"}}}},"400":{"description":"Bad Request","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ZoomInfo.Core.Foundations.ErrorResponseModel"}}}},"401":{"description":"Unauthorized","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ZoomInfo.Core.Foundations.ErrorResponseModel"}}}},"403":{"description":"Forbidden","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ZoomInfo.Core.Foundations.ErrorResponseModel"}}}},"404":{"description":"Not Found","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ZoomInfo.Core.Foundations.ErrorResponseModel"}}}},"429":{"description":"Too Many Requests","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ZoomInfo.Core.Foundations.ErrorResponseModel"}}}}},"tags":["Agents"],"security":[{"OAuth2Auth":["api:agent:read"]}],"x-api-roles":["fea:pls"]}},"/agent/v1/agents/{agentId}/runs/stream":{"post":{"operationId":"AgentsController_streamAgentRun","summary":"Start Agent Run (Stream)","description":"Starts a new agent run and streams progress and output over Server Sent\nEvents (`text/event-stream`).\n\nThe first event includes the runId as `task.id`. Store this value so you can\nretrieve the run later with\n[Get Agent Run](ref:agentscontroller_getagentrun) or reconnect using\n[Resume Agent Run Stream](ref:agentscontroller_resumeagentrunstream).\n\nThe stream includes status updates and artifact content as the agent runs.\nThe first artifact represents the primary response and may contain text and\nstructured data. A final status update indicates that the run has reached a\nterminal state.\n\nThis endpoint is available only for agents that support `STREAMING` in\n`capabilities.executionModes`. The request uses the same message format and\n`inputSchema` validation as\n[Start Agent Run](ref:agentscontroller_startagentrun).\nCustomer-defined Agent Teams on the platform do not currently support streaming.\nAgents that do not support streaming return `400 STREAMING_NOT_SUPPORTED`.","parameters":[{"name":"agentId","in":"path","required":true,"description":"The unique identifier of the agent to run.","schema":{"type":"string"}}],"responses":{"200":{"description":"The request has succeeded.","content":{"text/event-stream":{"schema":{"$ref":"#/components/schemas/AgentStreamEvent"}}}},"400":{"description":"Bad Request","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ZoomInfo.Core.Foundations.ErrorResponseModel"}}}},"401":{"description":"Unauthorized","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ZoomInfo.Core.Foundations.ErrorResponseModel"}}}},"403":{"description":"Forbidden","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ZoomInfo.Core.Foundations.ErrorResponseModel"}}}},"404":{"description":"Not Found","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ZoomInfo.Core.Foundations.ErrorResponseModel"}}}},"429":{"description":"Too Many Requests","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ZoomInfo.Core.Foundations.ErrorResponseModel"}}}}},"tags":["Agents"],"requestBody":{"required":true,"content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/StartAgentRunRequestBody"}}},"description":"The run request."},"security":[{"OAuth2Auth":["api:agent:execute"]}],"x-additional-content-types":["application/json"],"x-is-sse":true,"x-api-roles":["fea:pls"]}},"/agent/v1/agents/{agentId}/runs/{runId}":{"get":{"operationId":"AgentsController_getAgentRun","summary":"Get Agent Run","description":"Retrieves the current status and results of a specific agent run. Use the\nrun id returned in `data.id` by\n[Start Agent Run](ref:agentscontroller_startagentrun) or the first event of\na streaming run by\n[Start Agent Run (Stream)](ref:agentscontroller_streamagentrun).\n\nBy default, the endpoint returns the run's current state immediately. Set\n`returnImmediately=false` to wait for the run to reach a terminal state.\nRequests that remain open can wait for up to 300 seconds. If the request\ntimes out before the run completes, the response returns the in-progress run\nand execution continues in the background. Call this endpoint again with the\nsame run id to retrieve the latest status and results.\n\nWhen the run completes, the first item in `artifacts` contains the primary\nresponse and may include text and structured data. Additional artifacts,\nwhen present, contain supplementary output.\n\nFor agents that support streaming, use\n[Resume Agent Run Stream](ref:agentscontroller_resumeagentrunstream)\nto follow the run in real time.","parameters":[{"name":"agentId","in":"path","required":true,"description":"The unique identifier of the agent.","schema":{"type":"string"}},{"name":"runId","in":"path","required":true,"description":"The unique identifier of the run.","schema":{"type":"string"}},{"name":"returnImmediately","in":"query","required":false,"description":"When false, wait for the run to reach a terminal state, up to 300 seconds. Default true: return the current snapshot without blocking.","schema":{"type":"boolean"},"explode":false}],"responses":{"200":{"description":"Success","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/AgentRunResponse"}}}},"401":{"description":"Unauthorized","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ZoomInfo.Core.Foundations.ErrorResponseModel"}}}},"403":{"description":"Forbidden","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ZoomInfo.Core.Foundations.ErrorResponseModel"}}}},"404":{"description":"Not Found","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ZoomInfo.Core.Foundations.ErrorResponseModel"}}}},"429":{"description":"Too Many Requests","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ZoomInfo.Core.Foundations.ErrorResponseModel"}}}}},"tags":["Agents"],"security":[{"OAuth2Auth":["api:agent:read"]}],"x-api-roles":["fea:pls"]}},"/agent/v1/agents/{agentId}/runs/{runId}/stream":{"get":{"operationId":"AgentsController_resumeAgentRunStream","summary":"Resume Agent Run Stream","description":"Reconnects to an existing agent run and streams its progress and output\nusing Server-Sent Events (`text/event-stream`).\n\nUse this endpoint to reconnect to a run if a\n[Start Agent Run (Stream)](ref:agentscontroller_streamagentrun)\nconnection is interrupted, or to start streaming an existing run that was\noriginally started asynchronously or synchronously using\n[Start Agent Run](ref:agentscontroller_startagentrun).\n\nWhen reconnecting, the stream replays the run's existing artifacts from the\nbeginning, then continues with live updates until the run reaches a terminal\nstate. If the run has already completed, it returns the final artifacts and\nterminal status, then closes the stream.\n\nStreaming connections can remain open for up to 300 seconds. If the\nconnection ends before the run completes, the run continues in the\nbackground. Reconnect using the same run id, or use\n[Get Agent Run](ref:agentscontroller_getagentrun) to retrieve the latest\nstatus and results.\n\nThis endpoint is available only for agents that support `STREAMING` in\n`capabilities.executionModes`. Customer-defined Agent Teams on the platform\ndo not currently support streaming.\nAgents that do not support streaming return `400 STREAMING_NOT_SUPPORTED`.","parameters":[{"name":"agentId","in":"path","required":true,"description":"The unique identifier of the agent.","schema":{"type":"string"}},{"name":"runId","in":"path","required":true,"description":"The unique identifier of the run.","schema":{"type":"string"}}],"responses":{"200":{"description":"The request has succeeded.","content":{"text/event-stream":{"schema":{"$ref":"#/components/schemas/AgentStreamEvent"}}}},"400":{"description":"Bad Request","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ZoomInfo.Core.Foundations.ErrorResponseModel"}}}},"401":{"description":"Unauthorized","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ZoomInfo.Core.Foundations.ErrorResponseModel"}}}},"403":{"description":"Forbidden","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ZoomInfo.Core.Foundations.ErrorResponseModel"}}}},"404":{"description":"Not Found","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ZoomInfo.Core.Foundations.ErrorResponseModel"}}}},"429":{"description":"Too Many Requests","content":{"application/vnd.api+json":{"schema":{"$ref":"#/components/schemas/ZoomInfo.Core.Foundations.ErrorResponseModel"}}}}},"tags":["Agents"],"security":[{"OAuth2Auth":["api:agent:read"]}],"x-is-sse":true,"x-api-roles":["fea:pls"]}}},"security":[{"OAuth2Auth":[]}],"components":{"schemas":{"ZoomInfo.Core.Foundations.ErrorSourceModel":{"type":"object","properties":{"cookie":{"type":"string","description":"Identifies the cookie name that caused the issue"},"header":{"type":"string","description":"Identifies the header name that caused the error"},"pointer":{"type":"string","description":"An RFC 6901 compliant JSON pointer to the entity in the request body that caused the error"},"parameter":{"type":"string","description":"The name of the path or query parameter that caused the error"}}},"ZoomInfo.Core.Foundations.ErrorModel":{"type":"object","required":["id","code","status"],"properties":{"id":{"type":"string","description":"The unique id used to identify this specific error instance"},"code":{"type":"string","description":"The error code describing the error category. A full list of error codes can be found in the documentation for each service"},"detail":{"type":"string","description":"Message containing the specific details about this occurrence of the error"},"source":{"allOf":[{"$ref":"#/components/schemas/ZoomInfo.Core.Foundations.ErrorSourceModel"}],"description":"An optional object identifying which part of the request caused the error"},"status":{"type":"string","description":"The HTTP status code for the error"},"title":{"type":"string","description":"The error name that describes this type of error"}},"description":"The object describing a specific error from the API"},"ZoomInfo.Core.Foundations.ErrorResponseModel":{"type":"object","required":["errors"],"properties":{"detail":{"type":"string","description":"A high-level detail of the error(s) that occurred during the request"},"title":{"type":"string","description":"A high-level summary of the error(s) detected"},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ZoomInfo.Core.Foundations.ErrorModel"},"description":"The list of errors raised during the request"}},"description":"The standard error response body model for the ZoomInfo API."},"AgentManagedBy":{"type":"string","enum":["ZOOMINFO","TENANT"],"description":"Who operates the agent. ZoomInfo-managed agents are available to every eligible tenant; tenant agents (customer-built Agent Teams) are visible only within the owning tenant.","x-enumDescriptions":{"ZOOMINFO":"Created, hosted, and operated by ZoomInfo.","TENANT":"Configured by the customer (Agent Teams); scoped to the owning tenant."}},"AgentExecutionMode":{"type":"string","enum":["SYNC","STREAMING","ASYNC"],"description":"Execution modes an agent supports.","x-enumDescriptions":{"SYNC":"The connection is held until the run completes or the synchronous window elapses; an in-progress run is returned on expiry.","STREAMING":"Server-sent events streamed as the run progresses.","ASYNC":"Submit and receive the in-progress run at once; retrieve the outcome via Get Agent Run. Available for every agent that supports synchronous execution."}},"AgentCapabilities":{"type":"object","required":["executionModes","defaultInputModes","defaultOutputModes"],"properties":{"executionModes":{"type":"array","items":{"$ref":"#/components/schemas/AgentExecutionMode"},"description":"Execution modes this agent supports; each maps to an invocation endpoint."},"defaultInputModes":{"type":"array","items":{"type":"string"},"description":"MIME types accepted as run input."},"defaultOutputModes":{"type":"array","items":{"type":"string"},"description":"MIME types the agent can produce."},"interactive":{"type":"boolean","description":"OPTIONAL. Whether the agent can pause awaiting input (`TASK_STATE_INPUT_REQUIRED` / `TASK_STATE_AUTH_REQUIRED`) and be resumed by a follow-up run that sets `taskId`. `false` or absent (the case for every agent today) means runs are single-shot."}},"description":"Execution capabilities declared by the agent."},"AgentAttributes":{"type":"object","required":["name","description","active","managedBy","capabilities"],"properties":{"name":{"type":"string","description":"Display name of the agent."},"description":{"type":"string","description":"What the agent does."},"version":{"type":"string","description":"Semantic version of the agent definition. Omitted when the owning runtime does not version its agents."},"iconUrl":{"type":"string","format":"uri","description":"URL of the agent's icon image."},"active":{"type":"boolean","description":"Whether the agent is currently active and runnable."},"managedBy":{"allOf":[{"$ref":"#/components/schemas/AgentManagedBy"}],"description":"Who operates the agent."},"tags":{"type":"array","items":{"type":"string"},"description":"Tags assigned to the agent. Customer-assigned for tenant agents; curated defaults for ZoomInfo-managed agents."},"capabilities":{"allOf":[{"$ref":"#/components/schemas/AgentCapabilities"}],"description":"Declared execution capabilities."}},"description":"Attributes shared by every agent catalog entry."},"AgentMeta":{"type":"object","properties":{"createdAt":{"type":"string","format":"date-time","description":"When the agent was created."},"updatedAt":{"type":"string","format":"date-time","description":"When the agent definition last changed."},"createdBy":{"type":"string","description":"User id that created the agent (tenant agents)."},"modifiedBy":{"type":"string","description":"User id that last modified the agent (tenant agents)."}},"description":"Audit metadata for an agent catalog entry. Creator/modifier fields are present for tenant agents only."},"Agent":{"type":"object","required":["id","type","attributes"],"properties":{"id":{"type":"string","description":"The unique identifier for the resource"},"type":{"type":"string","description":"The type of the resource","default":"Agent","pattern":"Agent"},"attributes":{"allOf":[{"$ref":"#/components/schemas/AgentAttributes"}],"description":"The attributes defining the resource"},"meta":{"allOf":[{"$ref":"#/components/schemas/AgentMeta"}],"description":"Non-standard meta information about the resource"}},"description":"An agent catalog entry."},"CursorPageInfo":{"type":"object","required":["pageSize","totalCount"],"properties":{"pageSize":{"type":"integer","format":"uint32","description":"The page size as specified by the request."},"totalCount":{"type":"integer","format":"uint32","description":"The total count of results matching the current filters."}},"description":"Page details for a cursor-paged collection."},"CursorPagingMeta":{"type":"object","required":["page"],"properties":{"page":{"allOf":[{"$ref":"#/components/schemas/CursorPageInfo"}],"description":"Page details."}},"description":"Metadata for a cursor-paged collection."},"CursorPagingLinks":{"type":"object","properties":{"self":{"type":"string","format":"uri","description":"The link that generated the current response document"},"prev":{"type":"string","format":"uri","description":"A link to the previous page of data"},"next":{"type":"string","format":"uri","description":"A link to the next page of data"}},"description":"Links for a cursor-paged collection. `next` is omitted on the last page and `prev` on the first."},"AgentsListResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Agent"},"description":"The primary data of the document"},"meta":{"allOf":[{"$ref":"#/components/schemas/CursorPagingMeta"}],"description":"Non-standard meta information about the document"},"links":{"allOf":[{"$ref":"#/components/schemas/CursorPagingLinks"}],"description":"Links related to the primary data"}},"description":"Response containing a page of the agent catalog."},"AgentPartSchema":{"type":"object","required":["kind"],"properties":{"kind":{"type":"string","enum":["text","data","file"],"description":"Which part this entry declares: text | data | file."},"required":{"type":"boolean","description":"Whether a part of this kind must be present. Defaults to false."},"description":{"type":"string","description":"Field help for consoles and adapters (e.g. the prompt's placeholder)."},"schema":{"type":"object","additionalProperties":{},"description":"Data entries only: one standard JSON Schema (draft 2020-12) over the data part's payload -- the structured argument object for THIS agent. Plain JSON Schema, so standard validators and form generators apply directly."}},"description":"One declared part of the agent's input, discriminated by `kind` -- the\npart union's own vocabulary. At most one entry per kind: parts match\nentries BY KIND, never by position (part order carries no semantics);\narray order is the author's display order, so a prompt-first agent lists\nits text entry first."},"AgentTriggerType":{"type":"string","enum":["MANUAL","SCHEDULED"],"description":"How runs of this agent are initiated.","x-enumDescriptions":{"MANUAL":"Runs are started by an API call.","SCHEDULED":"Runs are started on a schedule; `scheduledDate` carries the next occurrence."}},"AgentDetailAttributes":{"type":"object","required":["name","description","active","managedBy","capabilities","triggerType"],"properties":{"name":{"type":"string","description":"Display name of the agent."},"description":{"type":"string","description":"What the agent does."},"version":{"type":"string","description":"Semantic version of the agent definition. Omitted when the owning runtime does not version its agents."},"iconUrl":{"type":"string","format":"uri","description":"URL of the agent's icon image."},"active":{"type":"boolean","description":"Whether the agent is currently active and runnable."},"managedBy":{"allOf":[{"$ref":"#/components/schemas/AgentManagedBy"}],"description":"Who operates the agent."},"tags":{"type":"array","items":{"type":"string"},"description":"Tags assigned to the agent. Customer-assigned for tenant agents; curated defaults for ZoomInfo-managed agents."},"capabilities":{"allOf":[{"$ref":"#/components/schemas/AgentCapabilities"}],"description":"Declared execution capabilities."},"inputSchema":{"type":"array","items":{"$ref":"#/components/schemas/AgentPartSchema"},"description":"This agent's declared input contract: an ARRAY of part schemas mirroring the run message's parts. A chat agent declares exactly [{kind: \"text\", required: true}]; an agent with structured input adds a data entry whose `schema` types that part's payload; an Agent Team declares one required data entry (Teams take no text part). ABSENT means no declared contract. Validated before a run is created -- see Start Agent Run."},"triggerType":{"allOf":[{"$ref":"#/components/schemas/AgentTriggerType"}],"description":"How runs of this agent are initiated."},"scheduledDate":{"type":"string","format":"date-time","description":"Next scheduled occurrence; present only when `triggerType` is `SCHEDULED`."}},"description":"Full agent detail: everything from the list entry plus the declared input contract and trigger metadata."},"AgentDetail":{"type":"object","required":["id","type","attributes"],"properties":{"id":{"type":"string","description":"The unique identifier for the resource"},"type":{"type":"string","description":"The type of the resource","default":"Agent","pattern":"Agent"},"attributes":{"allOf":[{"$ref":"#/components/schemas/AgentDetailAttributes"}],"description":"The attributes defining the resource"},"meta":{"allOf":[{"$ref":"#/components/schemas/AgentMeta"}],"description":"Non-standard meta information about the resource"}},"description":"An agent catalog entry with full input contract and trigger metadata."},"AgentDetailResponse":{"type":"object","required":["data"],"properties":{"data":{"allOf":[{"$ref":"#/components/schemas/AgentDetail"}],"description":"The primary data of the document"}},"description":"Response containing a single agent's full details."},"AgentTaskState":{"type":"string","enum":["TASK_STATE_UNSPECIFIED","TASK_STATE_SUBMITTED","TASK_STATE_WORKING","TASK_STATE_INPUT_REQUIRED","TASK_STATE_AUTH_REQUIRED","TASK_STATE_COMPLETED","TASK_STATE_FAILED","TASK_STATE_CANCELED","TASK_STATE_REJECTED"],"description":"Task lifecycle states for a run.\nTerminal: COMPLETED, FAILED, CANCELED, REJECTED. Interrupted:\nINPUT_REQUIRED, AUTH_REQUIRED. Everything else is non-terminal.\nConsumers must tolerate unknown values, treating UNSPECIFIED as the\nfallback for states this version does not define.\n\nThe service currently emits SUBMITTED, WORKING, COMPLETED, and FAILED\n(plus the UNSPECIFIED fallback). CANCELED and REJECTED are reserved for\ncancellation support; INPUT_REQUIRED and AUTH_REQUIRED are reserved for\ninteractive runs. Consumers should handle all nine states.","x-enumDescriptions":{"TASK_STATE_UNSPECIFIED":"The task state is unknown or has not been set. Non-terminal.","TASK_STATE_SUBMITTED":"The task was accepted and is waiting to begin. Non-terminal.","TASK_STATE_WORKING":"The agent is actively processing the task. Non-terminal.","TASK_STATE_INPUT_REQUIRED":"The agent needs additional user or client input. Interrupted.","TASK_STATE_AUTH_REQUIRED":"Additional authentication is required. Interrupted.","TASK_STATE_COMPLETED":"The task completed successfully. Terminal.","TASK_STATE_FAILED":"The task ended because of an execution error. Terminal.","TASK_STATE_CANCELED":"The task was canceled before completion. Terminal.","TASK_STATE_REJECTED":"The agent declined or could not accept the task. Terminal."}},"AgentMessageRole":{"type":"string","enum":["ROLE_UNSPECIFIED","ROLE_USER","ROLE_AGENT"],"description":"Who a message is from.","x-enumDescriptions":{"ROLE_UNSPECIFIED":"Unspecified.","ROLE_USER":"From the client to the agent.","ROLE_AGENT":"From the agent to the client."}},"AgentFileContent":{"type":"object","properties":{"uri":{"type":"string","format":"uri","description":"Link to downloadable content (e.g. a generated document)."},"bytes":{"type":"string","description":"Base64-encoded binary content."},"name":{"type":"string","description":"Display filename."},"mimeType":{"type":"string","description":"MIME type of the file content."}},"description":"File content: exactly one of `uri` (a link, e.g. the platform's\ntoken-gated document route) or `bytes` (base64). `name` is always present\non emitted files (the server falls back to the object type rather than\nemit a nameless file)."},"AgentArtifactPart":{"type":"object","properties":{"text":{"type":"string","description":"Inline text content (text part)."},"file":{"allOf":[{"$ref":"#/components/schemas/AgentFileContent"}],"description":"File content by link or bytes (file part)."},"data":{"description":"Structured content with no downloadable form, e.g. a created CRM record or a data agent's structured result (data part)."},"metadata":{"type":"object","additionalProperties":{},"description":"Producer-defined metadata for this part."}},"description":"One part of an artifact. Exactly one of `text`, `file`, or `data` is set,\nwhich determines the part's kind; `metadata` may accompany any. The\nmultipart protocol (chunk concatenation, rendering) keys off which one is\nset."},"AgentMessage":{"type":"object","required":["messageId","role","parts"],"properties":{"messageId":{"type":"string","description":"Unique message identifier."},"contextId":{"type":"string","description":"Conversation this message belongs to."},"taskId":{"type":"string","description":"Run this message belongs to (the runId)."},"role":{"allOf":[{"$ref":"#/components/schemas/AgentMessageRole"}],"description":"Who the message is from."},"parts":{"type":"array","items":{"$ref":"#/components/schemas/AgentArtifactPart"},"description":"The message's content parts."},"metadata":{"type":"object","additionalProperties":{},"description":"Producer-defined metadata."}},"description":"A message: the shape carried by `status.message`, `history`, and the stream `message` frame (that frame is reserved for future use and not currently emitted)."},"AgentRunStatus":{"type":"object","required":["state"],"properties":{"state":{"allOf":[{"$ref":"#/components/schemas/AgentTaskState"}],"description":"The task state."},"message":{"allOf":[{"$ref":"#/components/schemas/AgentMessage"}],"description":"A message elaborating this status, e.g. an agent's explanation of a failure or a prompt for further input."},"timestamp":{"type":"string","format":"date-time","description":"When this state was entered."}},"description":"Current status of a run."},"AgentRunMessage":{"type":"object","required":["parts"],"properties":{"parts":{"type":"array","items":{"$ref":"#/components/schemas/AgentArtifactPart"},"description":"The message's content parts. Each is exactly one of `text`, `file`, or `data`; at most one `data` part is allowed."}},"description":"The caller's message to the agent -- the run's entire input, as an ordered\nlist of content parts (the same part shape artifacts use). There is no\n`role` (the sender is always the caller) and no message id (the run itself\nis the identity), so `parts` is the whole of it.\n\nParts by kind: `text` parts carry prose and are joined into the agent's\nprompt; a `data` part carries the structured argument object the agent's\n`inputSchema` data entry types; `file` parts are declared in the shape but not yet\naccepted. AT MOST ONE `data` part may be present -- parts have no names and\ntheir order carries no meaning, so a second anonymous payload would be\nstructure no schema can address; nest multiple structured payloads inside\nthe one data object instead."},"AgentRunArtifact":{"type":"object","required":["artifactId","parts"],"properties":{"artifactId":{"type":"string","description":"Unique identifier of the artifact within the run."},"name":{"type":"string","description":"Display name of the artifact."},"description":{"type":"string","description":"What the artifact contains."},"parts":{"type":"array","items":{"$ref":"#/components/schemas/AgentArtifactPart"},"description":"The artifact's content parts. May carry more than one part, e.g. a text rendition and a structured `data` part."},"metadata":{"type":"object","additionalProperties":{},"description":"Producer-defined metadata, e.g. the tool that created the artifact."}},"description":"An output artifact of a run. Available when the terminal\nstate is COMPLETED; a completed run carries at least one, and the response\nartifact is the complete record of the result. A chat agent returns a\nsingle text part; a data agent returns a multi-part artifact carrying both\nrenditions, e.g. `parts: [ { text }, { data } ]`, where the `data` part\nholds the structured payload. Over the stream the parts arrive across\nappend-only chunks (the final `lastChunk` event delivers the data part\nbeside the text tail), so a streaming client assembles the same artifact a\nGet Agent Run returns. The first artifact of a run is its response; see\nAgentRunAttributes.artifacts."},"AgentRunError":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code, e.g. `AGENT_EXECUTION_FAILED`."},"message":{"type":"string","description":"Human-readable, sanitized explanation. Never carries internal system detail."},"retryable":{"type":"boolean","description":"Whether retrying the identical request may succeed. Defaults to false."}},"description":"Machine-readable failure details. Present when the run FAILED; may be present for CANCELED when a safe cancellation reason exists."},"RunInitiatorType":{"type":"string","enum":["USER","WORKFLOW","API"],"description":"The kind of identity that initiated a run.","x-enumDescriptions":{"USER":"An end user.","WORKFLOW":"An automated workflow.","API":"An API client credential."}},"RunInitiator":{"type":"object","required":["type","id"],"properties":{"type":{"allOf":[{"$ref":"#/components/schemas/RunInitiatorType"}],"description":"The kind of initiator."},"id":{"type":"string","description":"Identifier of the initiator (user id, workflow id, or API client id)."}},"description":"The identity that initiated the run."},"AgentRunAttributes":{"type":"object","required":["agentId","status","executionMode","input","initiatedBy"],"properties":{"agentId":{"type":"string","description":"The agent that was executed."},"status":{"allOf":[{"$ref":"#/components/schemas/AgentRunStatus"}],"description":"Current task status."},"executionMode":{"allOf":[{"$ref":"#/components/schemas/AgentExecutionMode"}],"description":"Execution mode used for the run."},"input":{"allOf":[{"$ref":"#/components/schemas/AgentRunMessage"}],"description":"The caller's input message, echoed back verbatim as it was sent -- the same `{ parts: [...] }` the run was started with. The run has no separate output field: the result is the run's `artifacts` (parts in, parts out)."},"contextId":{"type":"string","description":"The conversation this run belongs to, as a UUID, identical across the run's POST response, Get Agent Run, stream, and resume. For platform agents it is the conversation thread and can be passed back on a later run to continue it. For Teams agents it is always present -- a fresh server-minted per-run UUID -- but is an identity handle only: passing it back resumes nothing (Teams runs are single-shot)."},"artifacts":{"type":"array","items":{"$ref":"#/components/schemas/AgentRunArtifact"},"description":"The run's artifacts; present when the terminal state is COMPLETED, and at\nleast one is always present then. The FIRST artifact is the run's\nresponse: its text part is the reply prose, and a data part beside it\ncarries the structured result when the agent produced one. Further\nartifacts are supporting deliverables, e.g. generated documents (file\nparts) or referenced objects."},"error":{"allOf":[{"$ref":"#/components/schemas/AgentRunError"}],"description":"Machine-readable failure details; present when the run FAILED."},"durationMs":{"type":"integer","format":"int64","description":"Total execution duration in milliseconds. Present once the run reaches a terminal state."},"initiatedBy":{"allOf":[{"$ref":"#/components/schemas/RunInitiator"}],"description":"The identity that initiated the run."},"history":{"type":"array","items":{"$ref":"#/components/schemas/AgentMessage"},"description":"Task history: prior messages exchanged within the run's context."},"extensions":{"type":"object","additionalProperties":{},"description":"Extension data contributed to the run."}},"description":"Attributes describing an agent run."},"AgentRunMeta":{"type":"object","required":["createdAt","updatedAt"],"properties":{"createdAt":{"type":"string","format":"date-time","description":"When the run was created."},"startedAt":{"type":"string","format":"date-time","description":"When execution actually began."},"completedAt":{"type":"string","format":"date-time","description":"When the run reached a terminal state."},"updatedAt":{"type":"string","format":"date-time","description":"When the run last changed."},"totalCredits":{"type":"integer","format":"int32","description":"Total AI credits consumed. Present once the run reaches a terminal state."}},"description":"Timestamps and metering for an agent run."},"AgentRun":{"type":"object","required":["id","type","attributes"],"properties":{"id":{"type":"string","description":"The unique identifier for the resource"},"type":{"type":"string","description":"The type of the resource","default":"AgentRun","pattern":"AgentRun"},"attributes":{"allOf":[{"$ref":"#/components/schemas/AgentRunAttributes"}],"description":"The attributes defining the resource"},"meta":{"allOf":[{"$ref":"#/components/schemas/AgentRunMeta"}],"description":"Non-standard meta information about the resource"}},"description":"An agent run. The resource id is the runId, surfaced as taskId on every stream event."},"AgentRunResponse":{"type":"object","required":["data"],"properties":{"data":{"allOf":[{"$ref":"#/components/schemas/AgentRun"}],"description":"The primary data of the document"}},"description":"Response containing a single agent run."},"StartAgentRunAttributes":{"type":"object","required":["message"],"properties":{"message":{"allOf":[{"$ref":"#/components/schemas/AgentRunMessage"}],"description":"The run's input, as one message of content parts: `{ \"parts\": [ { \"text\": \"...\" }, { \"data\": { ... } } ] }`. Prose goes in `text` parts; the structured argument object (typed by the agent's `inputSchema` data entry) goes in a single `data` part. See AgentRunMessage for the rules."},"contextId":{"type":"string","description":"Conversation to continue this run within, as a UUID; omit to start fresh. Platform agents resume that conversation thread. Teams agents are single-shot: a supplied contextId is accepted and ignored (each Teams run gets a fresh server-minted context regardless). A malformed value returns `400` with a pointer to `/data/attributes/contextId`."},"returnImmediately":{"type":"boolean","description":"Whether the request returns immediately. Default `true` starts the run asynchronously and returns the in-progress run while execution continues in the background. Set `false` to keep the connection open while the agent executes, up to 300 seconds. If the run does not complete within that window, the response returns the in-progress run and execution continues in the background. Ignored by Start Agent Run (Stream), which always streams.","default":true},"taskId":{"type":"string","description":"OPTIONAL, and omitted for almost every call. Omit it to START a new run\n(the default, and the only mode implemented today). Set it to an existing\nrun's id ONLY to CONTINUE that run when it is paused awaiting input\n(`TASK_STATE_INPUT_REQUIRED` / `TASK_STATE_AUTH_REQUIRED`): the message is\ndelivered as the answer and the run resumes. This is A2A's `Message.taskId`\n(the run id is the taskId).\n\nOnly agents whose `capabilities.interactive` is `true` accept a taskId;\nothers return `400`. An unknown run returns `404`; a terminal or\nnot-awaiting-input run returns `409`. No agent declares `interactive` yet,\nso continuation is not available in practice -- the field is specified for\nforward compatibility, not for use today."}},"description":"Attributes for starting an agent run."},"StartAgentRunRequest":{"type":"object","required":["type","attributes"],"properties":{"type":{"type":"string","description":"The type of the resource","default":"StartAgentRunRequest","pattern":"StartAgentRunRequest"},"attributes":{"allOf":[{"$ref":"#/components/schemas/StartAgentRunAttributes"}],"description":"The attributes defining the resource"}},"description":"The run input as a JSON:API resource: `data.attributes` carries the message and optional contextId."},"StartAgentRunRequestBody":{"type":"object","required":["data"],"properties":{"data":{"allOf":[{"$ref":"#/components/schemas/StartAgentRunRequest"}],"description":"The primary data of the document"}},"description":"Request body for starting an agent run: a JSON:API document,\n`{ \"data\": { \"type\": \"StartAgentRunRequest\", \"attributes\": { ... } } }`,\nper the ZI public-API standard for request bodies. The run input lives in\n`data.attributes`; the same body is used by Start Agent Run and Start Agent\nRun (Stream)."},"AgentTask":{"type":"object","required":["id","status"],"properties":{"id":{"type":"string","description":"The run id. This is the first place a streaming-only client receives it: capture it here to poll Get Agent Run or reconnect via Resume Agent Run Stream after a drop."},"contextId":{"type":"string","description":"The conversation this task belongs to. Always populated: the server mints the conversation before the opening frame when the caller did not supply one, so a streaming-only caller holds the conversation handle from frame one."},"status":{"allOf":[{"$ref":"#/components/schemas/AgentRunStatus"}],"description":"Current task status."},"artifacts":{"type":"array","items":{"$ref":"#/components/schemas/AgentRunArtifact"},"description":"Output artifacts."},"history":{"type":"array","items":{"$ref":"#/components/schemas/AgentMessage"},"description":"Prior messages exchanged within the task's context."},"metadata":{"type":"object","additionalProperties":{},"description":"Producer-defined metadata."}},"description":"A full task snapshot carried in a stream frame. Emitted as the FIRST frame of every stream."},"AgentTaskStatusUpdateEvent":{"type":"object","required":["taskId","status"],"properties":{"taskId":{"type":"string","description":"The run this event belongs to: the runId."},"contextId":{"type":"string","description":"The conversation the run belongs to. Populated on every event from the WORKING frame onward: the platform thread for platform agents, or the server-minted per-run context for Teams agents."},"status":{"allOf":[{"$ref":"#/components/schemas/AgentRunStatus"}],"description":"The status entered."}},"description":"The run entered a new state. Emitted for\nTASK_STATE_WORKING once execution begins and again for the terminal state;\nthe terminal one is always the LAST frame of the stream. The opening\nSUBMITTED state is carried by the `task` frame, not by one of these (see\nAgentStreamEvent)."},"AgentTaskArtifactUpdateEvent":{"type":"object","required":["taskId","artifact"],"properties":{"taskId":{"type":"string","description":"The run this event belongs to (the runId)."},"contextId":{"type":"string","description":"The conversation the run belongs to (the platform thread, or the server-minted per-run context for Teams). Populated on every artifact event."},"artifact":{"allOf":[{"$ref":"#/components/schemas/AgentRunArtifact"}],"description":"The artifact chunk."},"append":{"type":"boolean","description":"Omitted or false on the first chunk of an artifact; true when this chunk's parts append to previously streamed content. An explicit false mid-stream means the artifact restarted and the accumulated content should be discarded."},"lastChunk":{"type":"boolean","description":"True on the artifact's final chunk."}},"description":"Artifact content produced mid-run. Chunks\nsharing an `artifactId` are concatenated by the client in arrival order."},"AgentStreamEvent":{"type":"object","properties":{"task":{"allOf":[{"$ref":"#/components/schemas/AgentTask"}],"description":"A full task snapshot. The FIRST frame of every stream is a `task` frame: on POST /runs/stream it carries state TASK_STATE_SUBMITTED and the runId as `task.id`; on reconnect it carries the run's current state (and finalized `artifacts` if terminal)."},"statusUpdate":{"allOf":[{"$ref":"#/components/schemas/AgentTaskStatusUpdateEvent"}],"description":"The run entered a new state. Emitted for WORKING and for the terminal state; the terminal one is always the last frame."},"artifactUpdate":{"allOf":[{"$ref":"#/components/schemas/AgentTaskArtifactUpdateEvent"}],"description":"Artifact content produced by the run."},"message":{"allOf":[{"$ref":"#/components/schemas/AgentMessage"}],"description":"A message. Reserved for future use; not currently emitted."}},"description":"One server-sent event of a streaming run.\nEXACTLY ONE member is present per event, discriminating the frame kind:\n`task`, `statusUpdate`, `artifactUpdate`, or `message`.\n\nThe FIRST frame of every stream is ALWAYS a `task` frame (the task snapshot). On POST /runs/stream its `task.status.state` is\nTASK_STATE_SUBMITTED, emitted before execution begins. A streaming-only\nclient MUST read the run id from this first frame -- `task.id` -- because it\nis the only place a caller who did not start the run over a non-streaming\nendpoint receives it, and it is what Get Agent Run and Resume Agent Run\nStream need to poll the run or reconnect to its stream after a drop.\n\nThe typical sequence is:\n`task(SUBMITTED)` -> `statusUpdate(WORKING)` -> `artifactUpdate`* ->\n`statusUpdate(terminal)`. A `statusUpdate` frame whose `status.state` is\nterminal is always the LAST frame."},"AgentRunsListResponse":{"type":"object","required":["data"],"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/AgentRun"},"description":"The primary data of the document"},"meta":{"allOf":[{"$ref":"#/components/schemas/CursorPagingMeta"}],"description":"Non-standard meta information about the document"},"links":{"allOf":[{"$ref":"#/components/schemas/CursorPagingLinks"}],"description":"Links related to the primary data"}},"description":"Response containing a page of agent runs."}},"securitySchemes":{"OAuth2Auth":{"type":"oauth2","flows":{"authorizationCode":{"authorizationUrl":"https://login.zoominfo.com","tokenUrl":"https://okta-login.zoominfo.com/oauth2/default/v1/token","scopes":{"api:agent:execute":"Allows customers to invoke available agents through registered OAuth applications.","api:agent:read":"Allows customers to view available agents, agent details, and agent run results through registered OAuth applications.","api:agent-pulses:read":"Read the authenticated user's pulses"}}}}}},"servers":[{"url":"https://api.zoominfo.com/gtm","description":"Base URL for the Agent API"}],"x-beta":true}