{"openapi":"3.1.0","info":{"title":"Opik (BYOK) API","version":"0.1.0","description":"Opik (BYOK) lets an AI assistant read your own Opik data through the Opik API with a key you supply (Comet API key). Read-only: 11 tools (list_projects, get_project, list_project_stats, list_traces, get_trace, list_spans, list_datasets, list_experiments, list_prompts, list_prompt_versions, list_feedback_definitions). The BYOK key travels with each request, is used for that one call only and is...\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://byok-opik.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"agent@connectorbay.com","url":"https://connectorbay.com/byok-opik/docs"},"termsOfService":"https://connectorbay.com/byok-opik/terms"},"servers":[{"url":"https://byok-opik.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/byok-opik/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 the Opik projects in the workspace with visibility and the time of the latest trace. Use for \"Which Opik projects d","description":"List the Opik projects in the workspace with visibility and the time of the latest trace. Use for \"Which Opik projects do I have\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results per page (1 to 100).","title":"Size"},"name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only projects whose name contains this text.","title":"Name"}},"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 Opik project by id. Use for \"Show details of Opik project 0192-project\".","description":"Get one Opik project by id. Use for \"Show details of Opik project 0192-project\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"project_id":{"description":"Project id as returned by list_projects.","maxLength":200,"title":"Project Id","type":"string"}},"required":["project_id"],"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/list_project_stats":{"post":{"operationId":"list_project_stats","summary":"List usage statistics per project: trace and thread counts, error counts, estimated cost, duration percentiles and avera","description":"List usage statistics per project: trace and thread counts, error counts, estimated cost, duration percentiles and average feedback scores. Use for \"How many traces and how much cost did each Opik project have last week\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results per page (1 to 100).","title":"Size"},"name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only projects whose name contains this text.","title":"Name"},"from_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only items at or after this ISO 8601 time, for example 2026-10-01T00:00:00Z.","title":"From Time"},"to_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only items at or before this ISO 8601 time, for example 2026-10-16T00:00:00Z.","title":"To Time"}},"title":"list_project_statsArguments","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_traces":{"post":{"operationId":"list_traces","summary":"List traces of one project, newest first, with timing, cost, span counts, errors, tags and feedback scores. Give project","description":"List traces of one project, newest first, with timing, cost, span counts, errors, tags and feedback scores. Give project_name or project_id. Use for \"Show the latest traces of the Opik project support-bot\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"project_name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Name of the project to read from (give this or project_id).","title":"Project Name"},"project_id":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Id of the project to read from, as returned by list_projects (give this or project_name).","title":"Project Id"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results per page (1 to 100).","title":"Size"},"from_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only items at or after this ISO 8601 time, for example 2026-10-01T00:00:00Z.","title":"From Time"},"to_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only items at or before this ISO 8601 time, for example 2026-10-16T00:00:00Z.","title":"To Time"},"search":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only traces whose content contains this text.","title":"Search"},"truncate":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"description":"True to shorten large input and output payloads.","title":"Truncate"}},"title":"list_tracesArguments","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_trace":{"post":{"operationId":"get_trace","summary":"Get one trace by id with its input, output, metadata, usage, cost and feedback scores. Use for \"Show Opik trace 0192-tra","description":"Get one trace by id with its input, output, metadata, usage, cost and feedback scores. Use for \"Show Opik trace 0192-trace in full\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"trace_id":{"description":"Trace id as returned by list_traces.","maxLength":200,"title":"Trace Id","type":"string"}},"required":["trace_id"],"title":"get_traceArguments","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_spans":{"post":{"operationId":"list_spans","summary":"List spans of one project, optionally for one trace or one type (general, tool, llm, guardrail), with model, provider, u","description":"List spans of one project, optionally for one trace or one type (general, tool, llm, guardrail), with model, provider, usage and cost. Use for \"Which LLM spans ran in Opik trace 0192-trace\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"project_name":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Name of the project to read from (give this or project_id).","title":"Project Name"},"project_id":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Id of the project to read from, as returned by list_projects (give this or project_name).","title":"Project Id"},"trace_id":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only spans of this trace id.","title":"Trace Id"},"type":{"anyOf":[{"enum":["general","tool","llm","guardrail"],"type":"string"},{"type":"null"}],"default":null,"description":"Only spans of this type.","title":"Type"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results per page (1 to 100).","title":"Size"},"from_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only items at or after this ISO 8601 time, for example 2026-10-01T00:00:00Z.","title":"From Time"},"to_time":{"anyOf":[{"maxLength":40,"type":"string"},{"type":"null"}],"default":null,"description":"Only items at or before this ISO 8601 time, for example 2026-10-16T00:00:00Z.","title":"To Time"},"truncate":{"anyOf":[{"type":"boolean"},{"type":"null"}],"default":true,"description":"True to shorten large input and output payloads.","title":"Truncate"}},"title":"list_spansArguments","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_datasets":{"post":{"operationId":"list_datasets","summary":"List evaluation datasets with item and experiment counts and the latest version. Use for \"Which Opik datasets do I have ","description":"List evaluation datasets with item and experiment counts and the latest version. Use for \"Which Opik datasets do I have and how many items are in them\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results per page (1 to 100).","title":"Size"},"name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only datasets whose name contains this text.","title":"Name"},"project_id":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only datasets linked to this project id.","title":"Project Id"}},"title":"list_datasetsArguments","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_experiments":{"post":{"operationId":"list_experiments","summary":"List experiments with dataset, status, trace counts, cost, average feedback scores and pass rate. Use for \"How did my la","description":"List experiments with dataset, status, trace counts, cost, average feedback scores and pass rate. Use for \"How did my latest Opik experiments score\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results per page (1 to 100).","title":"Size"},"name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only experiments whose name contains this text.","title":"Name"},"dataset_id":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only experiments run on this dataset id.","title":"Dataset Id"},"project_id":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only experiments of this project id.","title":"Project Id"}},"title":"list_experimentsArguments","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_prompts":{"post":{"operationId":"list_prompts","summary":"List versioned prompts in the prompt library with template structure (text or chat), tags and version count. Use for \"Wh","description":"List versioned prompts in the prompt library with template structure (text or chat), tags and version count. Use for \"Which prompts are stored in my Opik prompt library\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results per page (1 to 100).","title":"Size"},"name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only prompts whose name contains this text.","title":"Name"},"project_id":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only prompts of this project id.","title":"Project Id"}},"title":"list_promptsArguments","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_prompt_versions":{"post":{"operationId":"list_prompt_versions","summary":"List the versions of one prompt with the template text, commit id and change description. Use for \"Show the version hist","description":"List the versions of one prompt with the template text, commit id and change description. Use for \"Show the version history of Opik prompt 0192-prompt\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"prompt_id":{"description":"Prompt id as returned by list_prompts.","maxLength":200,"title":"Prompt Id","type":"string"},"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results per page (1 to 100).","title":"Size"},"search":{"anyOf":[{"maxLength":200,"type":"string"},{"type":"null"}],"default":null,"description":"Only versions whose template or change description contains this text.","title":"Search"}},"required":["prompt_id"],"title":"list_prompt_versionsArguments","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_feedback_definitions":{"post":{"operationId":"list_feedback_definitions","summary":"List the feedback score definitions (numerical, categorical or boolean) used to annotate traces. Use for \"Which feedback","description":"List the feedback score definitions (numerical, categorical or boolean) used to annotate traces. Use for \"Which feedback scores can I log in Opik\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"page":{"anyOf":[{"maximum":10000,"minimum":1,"type":"integer"},{"type":"null"}],"default":1,"description":"Page number, starting at 1.","title":"Page"},"size":{"anyOf":[{"maximum":100,"minimum":1,"type":"integer"},{"type":"null"}],"default":10,"description":"How many results per page (1 to 100).","title":"Size"},"name":{"anyOf":[{"maxLength":100,"type":"string"},{"type":"null"}],"default":null,"description":"Only definitions whose name contains this text.","title":"Name"},"type":{"anyOf":[{"enum":["numerical","categorical","boolean"],"type":"string"},{"type":"null"}],"default":null,"description":"Only definitions of this type.","title":"Type"}},"title":"list_feedback_definitionsArguments","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}}}}