{"openapi":"3.1.0","info":{"title":"Volkom Mesh — Agent API","description":"The API your agents use to report to Volkom Mesh.\n\n**Authentication:** send `Authorization: Bearer <token>` on every call. The\ntoken is either your workspace key (works for the whole fleet) or a per-agent\nkey; both are generated in the portal under *Connect your agents*.\n\n**Model:** a *run* is every event sharing one `run_id` (UUID), opened with\n`started` and always closed with `completed` or `failed`. Business KPIs go\nthrough the separate `/telemetry/business` channel.\n\nGuides and full reference: https://vmesh.volkom.ai/docs/\n","version":"0.2.0"},"paths":{"/api/v1/health":{"get":{"summary":"Health check","operationId":"health_api_v1_health_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"tags":["Status"],"description":"Returns `{\"status\": \"ok\"}` when the service is up. No auth."}},"/api/v1/telemetry":{"post":{"summary":"Send a run event","operationId":"ingest_telemetry_api_v1_telemetry_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TelemetryEventIn"}}},"required":true},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerToken":[]}],"tags":["Telemetry"],"description":"One execution event: `started`, `in_progress`, `completed` or `failed`. All events of a run share the same `run_id`. Returns 202 once the event is durably committed; `event_id` makes retries idempotent. Unknown agents are auto-registered (403 if the plan's agent cap is reached); disabled agents get `{\"status\": \"rejected\"}`. 503 means the ingest is saturated: back off and retry."}},"/api/v1/telemetry/batch":{"post":{"summary":"Send a batch of run events","description":"Same per-event contract as `/telemetry`, N events in one request and one commit. Use it for bursty fleets or to ship a whole run at once. Events from disabled agents are reported as rejected without failing the rest. 413 if the batch exceeds the event count or byte limit.","operationId":"ingest_telemetry_batch_api_v1_telemetry_batch_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/TelemetryBatchIn"}}},"required":true},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerToken":[]}],"tags":["Telemetry"]}},"/api/v1/telemetry/business":{"post":{"summary":"Send a run's business KPIs","description":"The business numbers of one run (`metrics`: key → number), tied to its `run_id`. Keys should be declared first via `/agents/register` so the portal knows their label, unit and aggregation; new keys are still accepted and stored.","operationId":"ingest_business_telemetry_api_v1_telemetry_business_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BusinessTelemetryIn"}}},"required":true},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerToken":[]}],"tags":["Telemetry"]}},"/api/v1/telemetry/llm":{"post":{"summary":"Send a run's LLM usage","description":"Tokens per model consumed by one run. Cost is computed at read time from the model's price list; only tokens are stored.","operationId":"ingest_llm_usage_api_v1_telemetry_llm_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LLMUsageIn"}}},"required":true},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerToken":[]}],"tags":["Telemetry"]}},"/api/v1/agents/register":{"post":{"summary":"Register or update an agent","operationId":"register_agent_api_v1_agents_register_post","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AgentRegister"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"security":[{"BearerToken":[]}],"tags":["Agent"],"description":"Idempotent upsert. Declares the agent's description, run cadence (`interval_seconds`, used for the *silent agent* alert), business KPI catalog (label / unit / agg), I/O contract and the configuration it needs (`config_schema`). A per-agent key can only register its own `agent_name`."}},"/api/v1/agents/model":{"get":{"summary":"Which LLM model to use","description":"The model the agent must use, as set by the workspace admin (per-agent override, workspace default, or the platform default). Ask before every run so the agent never runs a model the workspace does not allow.","operationId":"get_agent_model_api_v1_agents_model_get","security":[{"BearerToken":[]}],"parameters":[{"name":"agent_name","in":"query","required":true,"schema":{"type":"string","title":"Agent Name"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"tags":["Agent"]}},"/api/v1/agents/command-policy":{"get":{"summary":"Command policy for agentic agents","description":"Which shell commands the agent may run in its sandbox, as configured by the workspace admin.","operationId":"get_agent_command_policy_api_v1_agents_command_policy_get","security":[{"BearerToken":[]}],"parameters":[{"name":"agent_name","in":"query","required":true,"schema":{"type":"string","title":"Agent Name"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"tags":["Agent"]}},"/api/v1/agents/refresh-key":{"post":{"summary":"Rotate the calling key","description":"Returns a fresh token for the same (workspace, agent). The current key keeps working for a 5-minute grace window so in-flight work does not drop telemetry. Authenticate with the key being rotated.","operationId":"refresh_agent_key_api_v1_agents_refresh_key_post","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}},"security":[{"BearerToken":[]}],"tags":["Agent"]}},"/api/v1/heartbeat":{"post":{"summary":"Heartbeat","operationId":"heartbeat_api_v1_heartbeat_post","security":[{"BearerToken":[]}],"parameters":[{"name":"client_id","in":"query","required":true,"schema":{"type":"string","title":"Client Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"tags":["Telemetry"],"description":"Tells Mesh the process identified by `client_id` is alive. Optional: run events already prove liveness for scheduled agents."}},"/api/v1/agents/document":{"get":{"summary":"Pull the agent's configuration document","description":"The free-form configuration document edited in the portal, as is, with vault references left unresolved.","operationId":"pull_agent_document_api_v1_agents_document_get","security":[{"BearerToken":[]}],"parameters":[{"name":"agent_name","in":"query","required":true,"schema":{"type":"string","title":"Agent Name"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"tags":["Agent"]}},"/api/v1/agents/config":{"get":{"summary":"Pull the agent's resolved configuration","description":"The values the agent needs to run, keyed by the params it declared in `config_schema`. Secrets are resolved from the vault. Only the agent's own key can read them.","operationId":"pull_agent_config_api_v1_agents_config_get","security":[{"BearerToken":[]}],"parameters":[{"name":"agent_name","in":"query","required":true,"schema":{"type":"string","title":"Agent Name"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}},"tags":["Agent"]}}},"components":{"schemas":{"AgentRegister":{"properties":{"agent_name":{"type":"string","title":"Agent Name"},"agent_version":{"type":"string","title":"Agent Version","default":""},"description":{"type":"string","title":"Description","default":""},"telemetry_doc":{"type":"string","title":"Telemetry Doc","default":""},"business_kpis":{"items":{"$ref":"#/components/schemas/BusinessKPIDecl"},"type":"array","title":"Business Kpis","default":[]},"interval_seconds":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Interval Seconds"},"inputs":{"items":{"$ref":"#/components/schemas/IOField"},"type":"array","title":"Inputs","default":[]},"outputs":{"items":{"$ref":"#/components/schemas/IOField"},"type":"array","title":"Outputs","default":[]},"config_schema":{"anyOf":[{"$ref":"#/components/schemas/ConfigSchemaDecl"},{"type":"null"}]}},"type":"object","required":["agent_name"],"title":"AgentRegister"},"BusinessBreakdown":{"properties":{"metric":{"type":"string","maxLength":256,"title":"Metric"},"by":{"anyOf":[{"type":"string"},{"items":{"type":"string"},"type":"array"}],"title":"By"},"slices":{"additionalProperties":{"anyOf":[{"type":"number"},{"type":"integer"}]},"type":"object","maxProperties":1000,"title":"Slices","default":{}},"points":{"items":{"additionalProperties":{"anyOf":[{"type":"number"},{"type":"integer"},{"type":"string"}]},"type":"object"},"type":"array","maxItems":1000,"title":"Points","default":[]}},"type":"object","required":["metric","by"],"title":"BusinessBreakdown","description":"Un desglose dimensional de un KPI en una corrida. Dos formas, la que le\nquede mejor al agente:\n\n  1-D (atajo)   by=\"producto\", slices={\"Camperas\": 5200, \"Camisetas\": 3800}\n  N-D (general) by=[\"region\",\"canal\"],\n                points=[{\"region\":\"Norte\",\"canal\":\"Web\",\"value\":4000}, ...]\n\nAmbas se normalizan a filas (dims Map, value) en la tabla business_facts.\nEl `metric` ata el desglose a un KPI de `metrics` (el escalar total sigue\nyendo por ahí; esto es aditivo)."},"BusinessKPIDecl":{"properties":{"key":{"type":"string","title":"Key"},"label":{"type":"string","title":"Label","default":""},"unit":{"type":"string","title":"Unit","default":"count"},"agg":{"type":"string","title":"Agg","default":"sum"}},"type":"object","required":["key"],"title":"BusinessKPIDecl"},"BusinessTelemetryIn":{"properties":{"agent_name":{"type":"string","maxLength":256,"title":"Agent Name"},"agent_version":{"type":"string","maxLength":256,"title":"Agent Version","default":""},"client_id":{"type":"string","maxLength":256,"title":"Client Id","default":""},"run_id":{"type":"string","format":"uuid","title":"Run Id"},"timestamp":{"type":"string","format":"date-time","title":"Timestamp"},"metrics":{"additionalProperties":{"anyOf":[{"type":"number"},{"type":"integer"},{"type":"string"}]},"type":"object","maxProperties":100,"title":"Metrics","default":{}},"breakdowns":{"items":{"$ref":"#/components/schemas/BusinessBreakdown"},"type":"array","maxItems":100,"title":"Breakdowns","default":[]},"workflow_run_id":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Workflow Run Id"}},"type":"object","required":["agent_name","run_id","timestamp"],"title":"BusinessTelemetryIn","description":"Business KPIs for a run — separate channel from execution telemetry."},"ConfigParamDecl":{"properties":{"key":{"type":"string","title":"Key"},"label":{"type":"string","title":"Label","default":""},"value_type":{"type":"string","title":"Value Type","default":"string"},"required":{"type":"boolean","title":"Required","default":false},"help":{"type":"string","title":"Help","default":""},"default":{"type":"string","title":"Default","default":""},"opciones":{"items":{"type":"string"},"type":"array","title":"Opciones","default":[]},"restart_required":{"type":"boolean","title":"Restart Required","default":false}},"type":"object","required":["key"],"title":"ConfigParamDecl","description":"Descriptor de un parámetro, declarado por el agente.\n\nNO lleva la clasificación de seguridad (secreto / quién edita / quién ve): esa\nla decide el catálogo del control-plane. El registro se autentica con una key\nde agente —y una key de workspace puede registrar bajo cualquier nombre—, así\nque si el agente pudiera declararla, alcanzaría con re-registrar un schema para\nreclasificar un secreto como visible."},"ConfigSchemaDecl":{"properties":{"version":{"type":"integer","title":"Version","default":1},"params":{"items":{"$ref":"#/components/schemas/ConfigParamDecl"},"type":"array","title":"Params","default":[]}},"type":"object","title":"ConfigSchemaDecl"},"EventType":{"type":"string","enum":["started","completed","failed","in_progress"],"title":"EventType"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"IOField":{"properties":{"key":{"type":"string","title":"Key"},"type":{"type":"string","title":"Type","default":"any"},"required":{"type":"boolean","title":"Required","default":true}},"type":"object","required":["key"],"title":"IOField","description":"Contrato de un campo de input/output de un agente (para validar la\ncompatibilidad entre pasos de un workflow). `required` solo aplica a inputs."},"LLMUsageIn":{"properties":{"agent_name":{"type":"string","maxLength":256,"title":"Agent Name"},"agent_version":{"type":"string","maxLength":256,"title":"Agent Version","default":""},"client_id":{"type":"string","maxLength":256,"title":"Client Id","default":""},"run_id":{"type":"string","format":"uuid","title":"Run Id"},"timestamp":{"type":"string","format":"date-time","title":"Timestamp"},"model":{"type":"string","maxLength":256,"title":"Model"},"input_tokens":{"type":"integer","title":"Input Tokens","default":0},"output_tokens":{"type":"integer","title":"Output Tokens","default":0},"cache_read_tokens":{"type":"integer","title":"Cache Read Tokens","default":0},"cache_write_tokens":{"type":"integer","title":"Cache Write Tokens","default":0},"calls":{"type":"integer","title":"Calls","default":0},"workflow_run_id":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Workflow Run Id"}},"type":"object","required":["agent_name","run_id","timestamp","model"],"title":"LLMUsageIn","description":"Uso de LLM de una corrida, por modelo (canal separado). El agente reporta\nTOKENS; el costo/precio lo calcula el control-plane."},"TelemetryBatchIn":{"properties":{"events":{"items":{"$ref":"#/components/schemas/TelemetryEventIn"},"type":"array","title":"Events","default":[]}},"type":"object","title":"TelemetryBatchIn","description":"Lote de eventos para /telemetry/batch (mismo contrato que el individual)."},"TelemetryEventIn":{"properties":{"event_id":{"type":"string","maxLength":256,"title":"Event Id","default":""},"agent_name":{"type":"string","maxLength":256,"title":"Agent Name"},"agent_version":{"type":"string","maxLength":256,"title":"Agent Version","default":""},"client_id":{"type":"string","maxLength":256,"title":"Client Id"},"run_id":{"type":"string","format":"uuid","title":"Run Id"},"event":{"$ref":"#/components/schemas/EventType"},"timestamp":{"type":"string","format":"date-time","title":"Timestamp"},"duration_ms":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Duration Ms"},"records_processed":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Records Processed"},"error_type":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Error Type"},"error_message":{"anyOf":[{"type":"string","maxLength":16384},{"type":"null"}],"title":"Error Message"},"metadata":{"additionalProperties":{"type":"string"},"type":"object","maxProperties":100,"title":"Metadata","default":{}},"output":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Output"},"workflow_run_id":{"anyOf":[{"type":"string","maxLength":256},{"type":"null"}],"title":"Workflow Run Id"},"message":{"type":"string","maxLength":16384,"title":"Message","default":""},"level":{"type":"string","maxLength":32,"title":"Level","default":"info"},"category":{"type":"string","maxLength":256,"title":"Category","default":""},"source":{"type":"string","maxLength":256,"title":"Source","default":""},"seq":{"type":"integer","title":"Seq","default":0},"metrics":{"additionalProperties":{"type":"number"},"type":"object","maxProperties":100,"title":"Metrics","default":{}},"links":{"items":{"type":"string"},"type":"array","maxItems":50,"title":"Links","default":[]}},"type":"object","required":["agent_name","client_id","run_id","event","timestamp"],"title":"TelemetryEventIn"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"BearerToken":{"type":"http","scheme":"bearer","description":"Workspace or per-agent key, generated in the portal."}}},"tags":[{"name":"Telemetry","description":"Run events, business KPIs, LLM usage and heartbeat."},{"name":"Agent","description":"Registration, key rotation and what the agent reads to run (model, command policy, config)."},{"name":"Status","description":"Service health."}]}