{"openapi":"3.1.0","info":{"title":"Digital Ocean Gradient AI (BYOK) API","version":"0.1.0","description":"Digital Ocean Gradient AI (BYOK) lets an AI assistant read your own Digital Ocean Gradient AI data through the Digital Ocean Gradient AI API with a key you supply (personal access token with GenAI read scope). Read-only: 10 tools (list_agents, get_agent_usage, list_knowledge_bases, get_knowledge_base, list_knowledge_base_data_sources, list_indexing_jobs, list_models, search_model_catalog,...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-digitalocean-gradient-ai.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-digitalocean-gradient-ai/docs"},"termsOfService":"https://connectorbay.com/byok-digitalocean-gradient-ai/terms"},"servers":[{"url":"https://byok-digitalocean-gradient-ai.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-digitalocean-gradient-ai/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 GenAI agents with name, region, model, deployment status and URL, retrieval settings and web access flags (prompt t","description":"List GenAI agents with name, region, model, deployment status and URL, retrieval settings and web access flags (prompt text is not returned). Use for \"Which Gradient AI agents do I have and which are deployed\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"only_deployed":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to list only agents that are deployed.","title":"Only Deployed"},"per_page":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return per page.","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1; meta.pages in the answer is the total number of pages.","title":"Page"}},"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_usage":{"post":{"operationId":"get_agent_usage","summary":"Get token usage of one agent between two timestamps, split by usage type. Use for \"How many tokens did my agent use last","description":"Get token usage of one agent between two timestamps, split by usage type. Use for \"How many tokens did my agent use last week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"agent_uuid":{"description":"UUID of the agent, as shown by list_agents.","maxLength":64,"title":"Agent Uuid","type":"string"},"start":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Start of the period as an ISO 8601 timestamp, for example 2026-10-01T00:00:00Z.","title":"Start"},"stop":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"End of the period as an ISO 8601 timestamp.","title":"Stop"}},"required":["agent_uuid"],"title":"get_agent_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_knowledge_bases":{"post":{"operationId":"list_knowledge_bases","summary":"List knowledge bases with region, embedding model, reranking setting, tags and the status of the last indexing job. Use ","description":"List knowledge bases with region, embedding model, reranking setting, tags and the status of the last indexing job. Use for \"Which knowledge bases do I have and when were they last indexed\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"per_page":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return per page.","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1; meta.pages in the answer is the total number of pages.","title":"Page"}},"title":"list_knowledge_basesArguments","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_knowledge_base":{"post":{"operationId":"get_knowledge_base","summary":"Get one knowledge base with region, embedding model, reranking, tags and the last indexing job. Use for \"What is the ind","description":"Get one knowledge base with region, embedding model, reranking, tags and the last indexing job. Use for \"What is the indexing status of my knowledge base\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"knowledge_base_uuid":{"description":"UUID of the knowledge base, as shown by list_knowledge_bases.","maxLength":64,"title":"Knowledge Base Uuid","type":"string"}},"required":["knowledge_base_uuid"],"title":"get_knowledge_baseArguments","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_knowledge_base_data_sources":{"post":{"operationId":"list_knowledge_base_data_sources","summary":"List the data sources of a knowledge base with chunking settings and the result of each source's last indexing job. Use ","description":"List the data sources of a knowledge base with chunking settings and the result of each source's last indexing job. Use for \"What data sources feed my knowledge base and did they index cleanly\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"knowledge_base_uuid":{"description":"UUID of the knowledge base, as shown by list_knowledge_bases.","maxLength":64,"title":"Knowledge Base Uuid","type":"string"},"per_page":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return per page.","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1; meta.pages in the answer is the total number of pages.","title":"Page"}},"required":["knowledge_base_uuid"],"title":"list_knowledge_base_data_sourcesArguments","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_indexing_jobs":{"post":{"operationId":"list_indexing_jobs","summary":"List indexing jobs with phase, status, datasource counts, token counts and timing. Use for \"Did the latest knowledge bas","description":"List indexing jobs with phase, status, datasource counts, token counts and timing. Use for \"Did the latest knowledge base indexing job succeed\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"per_page":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return per page.","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1; meta.pages in the answer is the total number of pages.","title":"Page"}},"title":"list_indexing_jobsArguments","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_models":{"post":{"operationId":"list_models","summary":"List foundation and fine-tuned models available to agents, with provider, type, lifecycle status, context window and per","description":"List foundation and fine-tuned models available to agents, with provider, type, lifecycle status, context window and per-million-token prices. Use for \"Which models can I use in Gradient AI agents and what do they cost\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"public_only":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to list only models offered to every account.","title":"Public Only"},"per_page":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return per page.","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1; meta.pages in the answer is the total number of pages.","title":"Page"}},"title":"list_modelsArguments","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/search_model_catalog":{"post":{"operationId":"search_model_catalog","summary":"Search the model catalog by name with provider, type, context window, max output tokens and prices, sorted by name, pric","description":"Search the model catalog by name with provider, type, context window, max output tokens and prices, sorted by name, price or date. Use for \"Which coding models are in the Gradient AI catalog and what do they cost\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"search":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Text to search for in model names.","title":"Search"},"sort_by":{"anyOf":[{"enum":["MODEL_CATALOG_SORT_BY_CREATED_AT","MODEL_CATALOG_SORT_BY_NAME","MODEL_CATALOG_SORT_BY_PRICE"],"type":"string"},{"type":"null"}],"default":"MODEL_CATALOG_SORT_BY_CREATED_AT","description":"Order of the results.","title":"Sort By"},"sort_direction":{"anyOf":[{"enum":["SORT_DIRECTION_UNSPECIFIED","SORT_DIRECTION_ASC","SORT_DIRECTION_DESC"],"type":"string"},{"type":"null"}],"default":"SORT_DIRECTION_UNSPECIFIED","description":"Ascending or descending.","title":"Sort Direction"},"use_case":{"anyOf":[{"enum":["MODEL_CATALOG_USE_CASE_UNSPECIFIED","MODEL_CATALOG_USE_CASE_CODING","MODEL_CATALOG_USE_CASE_AGENTS","MODEL_CATALOG_USE_CASE_AUDIO","MODEL_CATALOG_USE_CASE_IMAGE","MODEL_CATALOG_USE_CASE_VIDEO","MODEL_CATALOG_USE_CASE_EMBEDDING"],"type":"string"},{"type":"null"}],"default":"MODEL_CATALOG_USE_CASE_UNSPECIFIED","description":"Only models for one use case.","title":"Use Case"},"per_page":{"anyOf":[{"maximum":200,"minimum":1,"type":"integer"},{"type":"null"}],"default":20,"description":"How many results to return per page.","title":"Per Page"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1; meta.pages in the answer is the total number of pages.","title":"Page"}},"title":"search_model_catalogArguments","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_genai_regions":{"post":{"operationId":"list_genai_regions","summary":"List the data center regions that serve Gradient AI inference or batch jobs, with their inference URLs. Use for \"In whic","description":"List the data center regions that serve Gradient AI inference or batch jobs, with their inference URLs. Use for \"In which regions can I run Gradient AI inference\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"serves_inference":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to keep only regions that serve inference.","title":"Serves Inference"},"serves_batch":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":false,"description":"True to keep only regions that serve batch jobs.","title":"Serves Batch"}},"title":"list_genai_regionsArguments","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_workspaces":{"post":{"operationId":"list_workspaces","summary":"List GenAI workspaces with name, description, creation time and the agents and evaluation test cases they hold. Use for ","description":"List GenAI workspaces with name, description, creation time and the agents and evaluation test cases they hold. Use for \"Which Gradient AI workspaces do I have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{},"title":"list_workspacesArguments","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}}}}