# AgentMark Docs

> AgentMark helps teams build reliable AI agents. Manage prompts, trace executions, run evaluations, and deploy agents with confidence.

## Docs

- [What's AgentMark?](https://puzzlet-9ba7bb98.mintlify.app/introduction/overview.md): AgentMark helps teams build reliable AI agents. Manage prompts, trace executions, run evaluations, and deploy, locally or with AgentMark Cloud.
- [Quickstart](https://puzzlet-9ba7bb98.mintlify.app/getting-started/quickstart.md): Create an AgentMark project and run your first prompt. Your AI editor does the wiring.
- [Set up your AgentMark client](https://puzzlet-9ba7bb98.mintlify.app/getting-started/client-setup.md): Create your AgentMark client, run prompts and experiments locally, and host it as a webhook so the Dashboard can execute against your code.
- [Coding agents](https://puzzlet-9ba7bb98.mintlify.app/coding-agents/overview.md): Connect AI coding agents and editors (Claude Code, Cursor, Codex, GitHub Copilot, VS Code, Zed) to AgentMark: the agent skill, the docs and gateway MCP servers, and the CLI.
- [AgentMark agent skill](https://puzzlet-9ba7bb98.mintlify.app/coding-agents/agent-skill.md): Install the AgentMark skill so Claude Code, Codex, Cursor, or GitHub Copilot already know how to author prompts, run experiments, and deploy in any project, including ones you didn't scaffold with create agentmark
- [Docs MCP](https://puzzlet-9ba7bb98.mintlify.app/coding-agents/docs-mcp.md): Wire the AgentMark docs MCP server into your AI editor so it can query AgentMark documentation and author .prompt.mdx files, datasets, and config from current guidance.
- [Gateway MCP](https://puzzlet-9ba7bb98.mintlify.app/coding-agents/gateway-mcp.md): Wire the AgentMark gateway MCP server (agentmark-mcp) into your AI editor to drive the full AgentMark API: traces, spans, scores, apps, environments, and alerts.
- [Core concepts](https://puzzlet-9ba7bb98.mintlify.app/introduction/core-concepts.md): AgentMark's core building blocks: organizations, apps, branches, environments, prompts, traces, datasets, evals, sessions, alerts, and annotations, and how they fit together.
- [Environments](https://puzzlet-9ba7bb98.mintlify.app/concepts/environments.md): The mental model behind AgentMark environments: dev tracks your branch live, and every environment gets its own isolated runtime, API keys, and environment variables.
- [Experiment identity and baselines](https://puzzlet-9ba7bb98.mintlify.app/concepts/experiment-identity.md): How AgentMark identifies an evaluation across runs: a stable experiment key, content-addressed tree hashes for baseline matching, the separate deployed-version commit axis, and input-hash row matching.
- [Build](https://puzzlet-9ba7bb98.mintlify.app/build/overview.md): Create, run, and version prompts in code or in the Dashboard
- [Create a prompt](https://puzzlet-9ba7bb98.mintlify.app/build/creating-prompts.md): Create prompts in the Dashboard visual editor or as local .prompt.mdx files
- [Prompt syntax](https://puzzlet-9ba7bb98.mintlify.app/build/syntax.md): Learn the AgentMark template syntax for creating dynamic prompts
- [Example prompts](https://puzzlet-9ba7bb98.mintlify.app/build/example-prompts.md): Copy-paste starter prompts that cover all four AgentMark generation types (object, text + tools, image, and speech), plus a runnable dataset for each.
- [Running prompts](https://puzzlet-9ba7bb98.mintlify.app/build/running-prompts.md): Run prompts from the Dashboard, CLI, or SDK with streaming, tracing, and caching
- [Migrate an existing prompt](https://puzzlet-9ba7bb98.mintlify.app/build/migrating-prompts.md): Move a prompt that already lives in your code (an inline SDK call, a Vercel AI SDK message, a LangChain ChatPromptTemplate, a LlamaIndex PromptTemplate) into a versioned AgentMark .prompt.mdx, and rewire the call site to load it. Keep your own SDK and model call.
- [Playground](https://puzzlet-9ba7bb98.mintlify.app/build/playground.md): Compare prompts and models side-by-side to find the best configuration before publishing
- [Version control](https://puzzlet-9ba7bb98.mintlify.app/build/version-control.md): Track, compare, and manage prompt versions in the AgentMark Dashboard
- [Tools and agents](https://puzzlet-9ba7bb98.mintlify.app/build/tools-and-agents.md): Reference tools by name in prompts, resolve them to implementations at your call site, and build multi-step agent workflows
- [MCP integration](https://puzzlet-9ba7bb98.mintlify.app/build/mcp.md): Reference Model Context Protocol (MCP) tools by name in AgentMark prompts, then connect the servers at your own call site.
- [File attachments](https://puzzlet-9ba7bb98.mintlify.app/build/file-attachments.md): Attach images and files to prompts using the ImageAttachment and FileAttachment tags.
- [Components](https://puzzlet-9ba7bb98.mintlify.app/build/components.md): Create reusable components to share prompting patterns across your prompts
- [Schema references](https://puzzlet-9ba7bb98.mintlify.app/build/schema-references.md): Reuse JSON schema definitions across AgentMark prompts with $ref
- [Type safety](https://puzzlet-9ba7bb98.mintlify.app/configure/type-safety.md): Generate TypeScript types from your prompt schemas for compile-time validation and autocomplete.
- [Generation types](https://puzzlet-9ba7bb98.mintlify.app/build/generation-types/overview.md): Understand the different types of content you can generate with AgentMark prompts
- [Generating objects](https://puzzlet-9ba7bb98.mintlify.app/build/generation-types/object.md): Generate structured JSON objects from prompts with schema validation using AgentMark.
- [Evaluate](https://puzzlet-9ba7bb98.mintlify.app/evaluate/overview.md): Test and improve your prompts with datasets, evaluators, experiments, and annotations
- [Datasets](https://puzzlet-9ba7bb98.mintlify.app/evaluate/datasets.md): Create test datasets for your prompts
- [Evaluations](https://puzzlet-9ba7bb98.mintlify.app/evaluate/writing-evals.md): Write evaluation functions to score prompt outputs
- [Running experiments](https://puzzlet-9ba7bb98.mintlify.app/evaluate/running-experiments.md): Test prompts with datasets in the Dashboard, CLI, or SDK
- [Human annotation](https://puzzlet-9ba7bb98.mintlify.app/evaluate/annotations.md): Score traces with human reviewers, individually or in structured batch queues
- [Observe](https://puzzlet-9ba7bb98.mintlify.app/observe/overview.md): Monitor, debug, and optimize your LLM applications with tracing, dashboards, and alerts
- [Tracing setup](https://puzzlet-9ba7bb98.mintlify.app/observe/tracing-setup.md): Instrument your application with the AgentMark SDK to capture traces, spans, and metrics
- [Span and attribute reference](https://puzzlet-9ba7bb98.mintlify.app/observe/span-reference.md): Span types, attributes, SpanOptions, SpanKind values, and the attributes that link traces to prompt versions
- [Traces and logs](https://puzzlet-9ba7bb98.mintlify.app/observe/traces-and-logs.md): Monitor and debug your prompts with distributed tracing
- [Sessions](https://puzzlet-9ba7bb98.mintlify.app/observe/sessions.md): Group related traces together for multi-turn conversations, workflows, and batch processing
- [Topics](https://puzzlet-9ba7bb98.mintlify.app/observe/topics.md): Automatically classify traces into facets and cluster them into named topics to surface recurring patterns across your production traffic
- [Metadata](https://puzzlet-9ba7bb98.mintlify.app/observe/metadata.md): Attach custom key-value pairs to traces for filtering, debugging, and context
- [Tags](https://puzzlet-9ba7bb98.mintlify.app/observe/tags.md): Attach string labels to traces for categorization and filtering
- [Filtering and search](https://puzzlet-9ba7bb98.mintlify.app/observe/filtering-and-search.md): Find specific traces and sessions using filters, date ranges, sorting, saved views, and shareable URLs
- [Dashboards](https://puzzlet-9ba7bb98.mintlify.app/observe/dashboards.md): Monitor operational metrics, evaluation scores, and custom analytics in one place
- [Autonomy Ladder](https://puzzlet-9ba7bb98.mintlify.app/observe/autonomy-ladder.md): How AgentMark classifies shipped work by autonomy level: the methodology behind Shipped Work by Autonomy Level and Delegated+ Share
- [Cost and token tracking](https://puzzlet-9ba7bb98.mintlify.app/observe/cost-and-token-tracking.md): Monitor LLM spending and token usage across your application
- [Alerts](https://puzzlet-9ba7bb98.mintlify.app/observe/alerts.md): Monitor your application with customizable alerts
- [Troubleshooting traces](https://puzzlet-9ba7bb98.mintlify.app/observe/troubleshooting.md): Why your AgentMark traces aren't showing up, the silent failures that drop spans, and how to fix each one.
- [PII masking](https://puzzlet-9ba7bb98.mintlify.app/observe/pii-masking.md): Redact sensitive data from traces before they leave your application
- [Environments](https://puzzlet-9ba7bb98.mintlify.app/deploy/environments-and-promotions.md): Run the same app across isolated environments like dev, staging, and prod.
- [Status checks](https://puzzlet-9ba7bb98.mintlify.app/deploy/status-checks.md): Fail pull/merge requests when AgentMark prompts don't compile, the same way you'd fail them for a broken build.
- [Regression gates](https://puzzlet-9ba7bb98.mintlify.app/deploy/regression-gates.md): Fail a PR or build when experiment scores regress against a baseline run
- [CI/CD](https://puzzlet-9ba7bb98.mintlify.app/deploy/ci-cd.md): Run AgentMark evals in your pipeline and gate pull/merge requests on the results.
- [Webhooks](https://puzzlet-9ba7bb98.mintlify.app/deploy/webhooks.md): Receive alert notifications from AgentMark Cloud via webhooks
- [Organizations and teams](https://puzzlet-9ba7bb98.mintlify.app/deploy/organizations-and-teams.md): Organizations, apps, and how they fit together
- [Users and access control](https://puzzlet-9ba7bb98.mintlify.app/deploy/users-and-access-control.md): Roles, permissions, custom roles, app-level access, and team management
- [API keys](https://puzzlet-9ba7bb98.mintlify.app/deploy/api-keys.md): Create, scope, and manage API keys for the AgentMark Gateway from the Dashboard.
- [Security](https://puzzlet-9ba7bb98.mintlify.app/deploy/security.md): How AgentMark protects your data: architecture, SSO, encryption, PII masking, retention, and subprocessors
- [Billing and usage](https://puzzlet-9ba7bb98.mintlify.app/deploy/billing-and-usage.md): Pricing tiers, usage limits, entitlements, and rate limits
- [Integrations](https://puzzlet-9ba7bb98.mintlify.app/integrations/overview.md): Send traces to AgentMark from any OpenTelemetry-instrumented app, via OpenInference, OpenLLMetry, or a raw OpenTelemetry setup.
- [Vercel integration](https://puzzlet-9ba7bb98.mintlify.app/integrations/vercel-connect.md): Apps deployed on Vercel attribute AgentMark traces to the right environment automatically, with no per-deployment configuration.
- [OpenTelemetry](https://puzzlet-9ba7bb98.mintlify.app/integrations/tracing/opentelemetry.md): Send OpenTelemetry traces to AgentMark from any instrumented app. The OTLP endpoint, authentication, and the semantic conventions AgentMark understands.
- [OpenInference](https://puzzlet-9ba7bb98.mintlify.app/integrations/tracing/openinference.md): Trace LangChain, LlamaIndex, OpenAI Agents SDK, CrewAI, DSPy, and other OpenInference-instrumented frameworks in AgentMark.
- [OpenLLMetry](https://puzzlet-9ba7bb98.mintlify.app/integrations/tracing/openllmetry.md): Trace LLM apps instrumented with OpenLLMetry (Traceloop) or OpenLIT in AgentMark, across providers, frameworks, and agent libraries.
- [Trace grouping](https://puzzlet-9ba7bb98.mintlify.app/integrations/tracing/agentmark-otel.md): Group AgentMark traces by session, user, and metadata with the @agentmark-ai/otel OpenTelemetry helper.
- [LangChain](https://puzzlet-9ba7bb98.mintlify.app/integrations/frameworks/langchain.md): Trace LangChain and LangGraph apps in AgentMark using the OpenInference instrumentor, in Python and JavaScript.
- [CrewAI](https://puzzlet-9ba7bb98.mintlify.app/integrations/frameworks/crewai.md): Trace CrewAI agents and crews in AgentMark using the OpenInference instrumentor.
- [LlamaIndex](https://puzzlet-9ba7bb98.mintlify.app/integrations/frameworks/llamaindex.md): Trace LlamaIndex queries, retrievers, and agents in AgentMark using the OpenInference instrumentor.
- [DSPy](https://puzzlet-9ba7bb98.mintlify.app/integrations/frameworks/dspy.md): Trace DSPy modules and optimizers in AgentMark using the OpenInference instrumentor.
- [OpenAI Agents SDK](https://puzzlet-9ba7bb98.mintlify.app/integrations/frameworks/openai-agents.md): Trace OpenAI Agents SDK runs in AgentMark using the OpenInference instrumentor, in Python and JavaScript.
- [Vercel AI SDK](https://puzzlet-9ba7bb98.mintlify.app/integrations/frameworks/vercel-ai-sdk.md): Trace Vercel AI SDK calls in AgentMark by exporting its OpenTelemetry spans to the AgentMark OTLP endpoint.
- [Pydantic AI](https://puzzlet-9ba7bb98.mintlify.app/integrations/frameworks/pydantic-ai.md): Trace Pydantic AI agents in AgentMark using the OpenInference span processor.
- [AutoGen](https://puzzlet-9ba7bb98.mintlify.app/integrations/frameworks/autogen.md): Trace Microsoft AutoGen (AgentChat) agents in AgentMark using the OpenInference instrumentor.
- [Agno](https://puzzlet-9ba7bb98.mintlify.app/integrations/frameworks/agno.md): Trace Agno agents in AgentMark using the OpenInference instrumentor.
- [Semantic Kernel](https://puzzlet-9ba7bb98.mintlify.app/integrations/frameworks/semantic-kernel.md): Trace Microsoft Semantic Kernel in AgentMark using its native OpenTelemetry GenAI diagnostics.
- [smolagents](https://puzzlet-9ba7bb98.mintlify.app/integrations/frameworks/smolagents.md): Trace Hugging Face smolagents in AgentMark using the OpenInference instrumentor.
- [Haystack](https://puzzlet-9ba7bb98.mintlify.app/integrations/frameworks/haystack.md): Trace Haystack pipelines in AgentMark using the OpenInference instrumentor.
- [Google ADK](https://puzzlet-9ba7bb98.mintlify.app/integrations/frameworks/google-adk.md): Trace Google Agent Development Kit (ADK) agents in AgentMark using the OpenInference instrumentor.
- [Mastra](https://puzzlet-9ba7bb98.mintlify.app/integrations/frameworks/mastra.md): Trace Mastra agents in AgentMark using Mastra's OpenTelemetry exporter.
- [OpenAI](https://puzzlet-9ba7bb98.mintlify.app/integrations/providers/openai.md): Trace OpenAI API calls in AgentMark using the OpenInference instrumentor.
- [Anthropic](https://puzzlet-9ba7bb98.mintlify.app/integrations/providers/anthropic.md): Trace Anthropic (Claude) API calls in AgentMark using the OpenInference instrumentor.
- [Amazon Bedrock](https://puzzlet-9ba7bb98.mintlify.app/integrations/providers/bedrock.md): Trace Amazon Bedrock calls in AgentMark using the OpenInference instrumentor.
- [Google Gemini](https://puzzlet-9ba7bb98.mintlify.app/integrations/providers/google-gemini.md): Trace Google Gemini API calls in AgentMark using the OpenInference instrumentor.
- [Google Vertex AI](https://puzzlet-9ba7bb98.mintlify.app/integrations/providers/vertex-ai.md): Trace Google Vertex AI calls in AgentMark using the OpenInference instrumentor.
- [Mistral](https://puzzlet-9ba7bb98.mintlify.app/integrations/providers/mistral.md): Trace Mistral API calls in AgentMark using the OpenInference instrumentor.
- [Groq](https://puzzlet-9ba7bb98.mintlify.app/integrations/providers/groq.md): Trace Groq API calls in AgentMark using the OpenInference instrumentor.
- [OpenAI-compatible providers](https://puzzlet-9ba7bb98.mintlify.app/integrations/providers/openai-compatible.md): Trace OpenAI-compatible providers (OpenRouter, Together, Fireworks, DeepSeek, Ollama, and more) in AgentMark.
- [LiteLLM](https://puzzlet-9ba7bb98.mintlify.app/integrations/gateways/litellm.md): Trace LiteLLM calls in AgentMark using the OpenInference instrumentor.
- [Portkey](https://puzzlet-9ba7bb98.mintlify.app/integrations/gateways/portkey.md): Trace Portkey gateway calls in AgentMark using the OpenInference instrumentor.
- [CLI reference](https://puzzlet-9ba7bb98.mintlify.app/reference/cli-commands.md): Complete reference for all AgentMark CLI commands
- [Python dev server](https://puzzlet-9ba7bb98.mintlify.app/reference/python-dev-server.md): Running the AgentMark development server with Python
- [Troubleshooting](https://puzzlet-9ba7bb98.mintlify.app/reference/troubleshooting.md): Solutions to common errors and issues when using AgentMark
- [Project config](https://puzzlet-9ba7bb98.mintlify.app/configure/project-config.md): How to configure AgentMark for your application
- [Model schemas](https://puzzlet-9ba7bb98.mintlify.app/configure/model-schemas.md): Add built-in and custom models in AgentMark
- [Loaders](https://puzzlet-9ba7bb98.mintlify.app/configure/loaders.md): Load prompts from different sources using ApiLoader and FileLoader
- [Environment variables](https://puzzlet-9ba7bb98.mintlify.app/configure/environment-variables.md): Complete reference for all environment variables used by AgentMark
- [Overview](https://puzzlet-9ba7bb98.mintlify.app/templatedx/introduction.md): TemplateDX is an extensible templating engine for AI prompts, built on Markdown and JSX.
- [Quickstart](https://puzzlet-9ba7bb98.mintlify.app/templatedx/quickstart.md): Install TemplateDX and render your first prompt template.
- [Syntax overview](https://puzzlet-9ba7bb98.mintlify.app/templatedx/syntax.md): Complete syntax reference for TemplateDX
- [Editor integration](https://puzzlet-9ba7bb98.mintlify.app/templatedx/syntax-highlighting.md): Set up syntax highlighting, schema validation, and MCP integration for TemplateDX files in VS Code, Cursor, Zed, and Claude Code.
- [Variables](https://puzzlet-9ba7bb98.mintlify.app/templatedx/variables.md): Pass dynamic data into TemplateDX templates via the props object.
- [Expressions](https://puzzlet-9ba7bb98.mintlify.app/templatedx/expressions.md): Use JavaScript-like expressions in TemplateDX templates for dynamic content and conditional logic.
- [Tags](https://puzzlet-9ba7bb98.mintlify.app/templatedx/tags.md): Use built-in and custom tags in TemplateDX to control template flow and transform data.
- [Filters](https://puzzlet-9ba7bb98.mintlify.app/templatedx/filters.md): Transform and format template values with built-in TemplateDX filter functions.
- [Components](https://puzzlet-9ba7bb98.mintlify.app/templatedx/components.md): Create reusable template fragments in TemplateDX for shared prompt logic and structure.
- [API reference](https://puzzlet-9ba7bb98.mintlify.app/api-reference/overview.md): Programmatic access to the AgentMark Gateway API.
- [Authentication](https://puzzlet-9ba7bb98.mintlify.app/api-reference/authentication.md): How to authenticate with the AgentMark Gateway API.
- [API versioning & stability](https://puzzlet-9ba7bb98.mintlify.app/api-reference/versioning.md): How the AgentMark Gateway API versions itself, what counts as a breaking change, and how AgentMark communicates deprecations.
- [Ingest traces](https://puzzlet-9ba7bb98.mintlify.app/api-reference/traces/ingest-traces.md): Ingest trace data in [OTLP (OpenTelemetry Protocol)](https://opentelemetry.io/docs/specs/otlp/) format. Traces are buffered in a queue and processed asynchronously.
- [List traces](https://puzzlet-9ba7bb98.mintlify.app/api-reference/traces/list-traces.md): Retrieve a paginated list of traces. Supports filtering by status, user, model, and date range.
- [Search traces](https://puzzlet-9ba7bb98.mintlify.app/api-reference/traces/search-traces.md): Search traces with structured JSON filters — the programmatic form of the `filter` string DSL on `GET /v1/traces`. `filters` is an AND-list of predicates (`{field, operator, value}`) and one-level OR-groups (`{or: [...]}`). Adds membership operators `in`, `notIn`, and `between` that have no string-D…
- [Get trace](https://puzzlet-9ba7bb98.mintlify.app/api-reference/traces/get-trace.md): Retrieve a specific trace by ID, including all its spans.
- [List spans for a trace](https://puzzlet-9ba7bb98.mintlify.app/api-reference/spans/list-spans-for-a-trace.md): Returns every span belonging to the given trace, ordered by start time. Not paginated — traces are bounded by span volume (capped at ingest), so the full list is returned in a single response.
- [Get span I/O detail](https://puzzlet-9ba7bb98.mintlify.app/api-reference/spans/get-span-io-detail.md): Returns the full input/output payload for a specific span, plus parsed output objects, tool calls, and the span’s custom metadata (reserved internal namespaces excluded). Useful for rendering a single span in isolation without loading the entire trace.
- [Ingest coding-agent sessions (outerlayer sync)](https://puzzlet-9ba7bb98.mintlify.app/api-reference/agents/ingest-coding-agent-sessions-outerlayer-sync.md): Ingests a batch of canonical AgentSessions (schemaVersion 1) plus their content-addressed image blobs. Each session is tier-clamped to the tenant ceiling, secret-scrubbed, and mapped to spans. Deterministic ids make re-sync idempotent. Sessions are validated individually: a malformed session is reje…
- [Fetch an agent session image blob](https://puzzlet-9ba7bb98.mintlify.app/api-reference/agents/fetch-an-agent-session-image-blob.md): Returns the raw bytes of a content-addressed agent-session image (sha256). Scoped to the API key's tenant and app.
- [Ingest eval trial results](https://puzzlet-9ba7bb98.mintlify.app/api-reference/evals/ingest-eval-trial-results.md): Persists full eval TrialResults: per trial, thin score rows for the queryable index (`eval.trial.resolved`, `eval.trial.cost_usd`, `eval.trial.duration_ms`) plus a full-fidelity artifact blob. Trials are validated individually — a malformed trial is rejected without failing the batch. Deterministic…
- [Fetch an eval run job (worker)](https://puzzlet-9ba7bb98.mintlify.app/api-reference/evals/fetch-an-eval-run-job-worker.md): Returns the job spec for one eval run. Machine endpoint for the per-run eval worker: the API key must be the run's own dispatch-minted key; anything else is a 404.
- [Report eval run status (worker)](https://puzzlet-9ba7bb98.mintlify.app/api-reference/evals/report-eval-run-status-worker.md): Worker lifecycle reporting: claim (running), complete (succeeded + card), or fail. Terminal statuses also revoke the run's API key — the credential dies with the run. Transitions out of a terminal status are rejected (409) so a zombie machine cannot overwrite a completed run.
- [Record an env-build escalation (worker)](https://puzzlet-9ba7bb98.mintlify.app/api-reference/evals/record-an-env-build-escalation-worker.md): The escalation sink: an env whose repair ladder exhausted its budget becomes a human-readable ticket. tenant/app/eval_run_id are stamped from the key's run binding, never from the body.
- [List spans](https://puzzlet-9ba7bb98.mintlify.app/api-reference/spans/list-spans.md): Query spans across all traces. Supports filtering by type, status, model, name, and duration range.
- [Search spans](https://puzzlet-9ba7bb98.mintlify.app/api-reference/spans/search-spans.md): Search spans with structured JSON filters — the programmatic form of the `filter` string DSL on `GET /v1/spans`. `filters` is an AND-list of predicates (`{field, operator, value}`) and one-level OR-groups (`{or: [...]}`). Adds membership operators `in`, `notIn`, and `between`. Valid fields and opera…
- [Get span](https://puzzlet-9ba7bb98.mintlify.app/api-reference/spans/get-span.md): Fetch a single span by its globally-unique span_id, without needing its trace_id. Returns the full span: metadata plus its input/output payload (the span analog of GET /v1/traces/:traceId).
- [Fetch an offloaded span field blob](https://puzzlet-9ba7bb98.mintlify.app/api-reference/spans/fetch-an-offloaded-span-field-blob.md): Returns the full content of a span field payload (input/output/...) that was offloaded to object storage at ingest. Reference the object via a BlobRefs[].blob_id from a span. Tenant-scoped.
- [Create score](https://puzzlet-9ba7bb98.mintlify.app/api-reference/scoring/create-score.md): Create a score record for a span or trace. Scores are used to track quality metrics, evaluation results, and human feedback.
- [Create scores (batch)](https://puzzlet-9ba7bb98.mintlify.app/api-reference/scoring/create-scores-batch.md): Create up to 1000 scores in a single request. Each item is validated independently and the response always contains a per-item results array.
- [List scores](https://puzzlet-9ba7bb98.mintlify.app/api-reference/scoring/list-scores.md): Returns a paginated list of scores for the authenticated application. Supports filtering by resource, name, source, and date range.
- [Search scores](https://puzzlet-9ba7bb98.mintlify.app/api-reference/scoring/search-scores.md): Search scores with structured JSON filters. `filters` is an AND-list of predicates (`{field, operator, value}`) and one-level OR-groups (`{or: [...]}`) over the score fields: name, score, source, user_id, resource_id, label, created_at. Membership (`in`, `notIn`) and range (`between`) operators are…
- [Get score](https://puzzlet-9ba7bb98.mintlify.app/api-reference/scoring/get-score.md): Retrieve a single score record by ID. Returns the full score object including its value, label, reason, and source.
- [Get score aggregations](https://puzzlet-9ba7bb98.mintlify.app/api-reference/scoring/get-score-aggregations.md): Returns aggregated statistics for scores grouped by name. Useful for understanding score distributions across your application.
- [Get score names](https://puzzlet-9ba7bb98.mintlify.app/api-reference/scoring/get-score-names.md): Returns a list of distinct score names used in your application. Useful for building filter dropdowns and discovering available score types.
- [Delete score](https://puzzlet-9ba7bb98.mintlify.app/api-reference/scoring/delete-score.md): Delete a score record by ID.
- [Launch a worker run](https://puzzlet-9ba7bb98.mintlify.app/api-reference/workers/launch-a-worker-run.md): Launches a terminal coding agent against the app's connected repo on managed compute: it clones the code, does the task, and delivers a branch + pull request. Poll `GET /v1/workers/runs/{runId}` for the outcome, or hand a human the returned `url` — the dashboard's live chat thread for the run.
- [Get a worker run](https://puzzlet-9ba7bb98.mintlify.app/api-reference/workers/get-a-worker-run.md): Status, outcome, and delivery (branch / PR) for a run, plus the dashboard deep link to its live thread. Runs are app-scoped to the caller's key.
- [Start a persistent worker session](https://puzzlet-9ba7bb98.mintlify.app/api-reference/workers/start-a-persistent-worker-session.md): Creates a persistent environment (a durable workspace the agent resumes across turns) and dispatches its first turn. Continue it with `POST /v1/workers/environments/{envId}/turns`. The returned `url` opens the session as a live chat thread in the dashboard.
- [Continue a worker session](https://puzzlet-9ba7bb98.mintlify.app/api-reference/workers/continue-a-worker-session.md): Dispatches a follow-up turn in a persistent session: the agent resumes its prior conversation in the same warm workspace and checkpoints to the session's work branch. One turn at a time — a concurrent turn returns 409 `environment_busy`.
- [Get a worker session](https://puzzlet-9ba7bb98.mintlify.app/api-reference/workers/get-a-worker-session.md): The session and its turn thread (oldest first), plus the dashboard deep link that opens it as a live chat.
- [List environments](https://puzzlet-9ba7bb98.mintlify.app/api-reference/environments/list-environments.md): Returns environments for the authenticated application, default env first. Each env carries pin state (`current_version` — 0 when no-pin — plus `current_commit_sha`, the git commit of the pinned deployment, NULL when no-pin) and a stable `epoch` that distinguishes env instances across name reuse aft…
- [Create environment](https://puzzlet-9ba7bb98.mintlify.app/api-reference/environments/create-environment.md): Creates a new environment in the current app. The env starts in the no-pin state. No runtime is provisioned and no API key is auto-minted; the response includes `api_key_creation_url` for the post-create CTA.
- [Get environment](https://puzzlet-9ba7bb98.mintlify.app/api-reference/environments/get-environment.md): Returns a single environment by id. Includes `cascade_preview` (the count of api_key rows that would be deleted on env delete; `alert_count` and `deployment_count` are always 0 and remain only for response-shape compatibility) and `in_flight_saga_id` (id of the most-recent pending/snapshotting/deplo…
- [Delete environment](https://puzzlet-9ba7bb98.mintlify.app/api-reference/environments/delete-environment.md): Hard-deletes a non-default environment after a typed-name confirmation. Cascade order: env row → CASCADE removes api_key. An environment owns no runtime, so nothing outside the database is torn down.
- [Get capabilities](https://puzzlet-9ba7bb98.mintlify.app/api-reference/capabilities/get-capabilities.md): Returns a map of available API endpoints for the current target (cloud or local). Use this to discover which features are supported before calling other endpoints.
- [Get LLM pricing](https://puzzlet-9ba7bb98.mintlify.app/api-reference/pricing/get-llm-pricing.md): Returns per-model pricing for cost calculation. Response is a dynamic map keyed by model ID (e.g. `gpt-5`, `claude-opus-4-6`). Prices are per 1,000 tokens.
- [List API keys](https://puzzlet-9ba7bb98.mintlify.app/api-reference/api-keys/list-api-keys.md): Returns API keys for the authenticated tenant. Plaintext is never returned on this endpoint — record it at creation time.
- [Create API key](https://puzzlet-9ba7bb98.mintlify.app/api-reference/api-keys/create-api-key.md): Creates a new API key. The plaintext key is returned EXACTLY ONCE in `data.plaintext_key` — record it immediately. Subsequent reads expose only metadata.
- [Revoke API key](https://puzzlet-9ba7bb98.mintlify.app/api-reference/api-keys/revoke-api-key.md): Revokes the API key and removes its local metadata row. Note: a brief revocation lag may occur — the gateway caches verified credentials for a short TTL, so a freshly-revoked key may still verify until the cache expires.
- [List apps](https://puzzlet-9ba7bb98.mintlify.app/api-reference/apps/list-apps.md): Returns apps for the authenticated tenant, newest first. Use `?name=<exact>` to look up a specific app by name without paginating.
- [Create app](https://puzzlet-9ba7bb98.mintlify.app/api-reference/apps/create-app.md): Creates a new app in the authenticated tenant. `runtime` defaults to `nodejs` if omitted.
- [Get app](https://puzzlet-9ba7bb98.mintlify.app/api-reference/apps/get-app.md): Returns a single app by ID.
- [Update app](https://puzzlet-9ba7bb98.mintlify.app/api-reference/apps/update-app.md): Updates writable fields on an app. PATCH semantics — any subset of `name`, `display_name`, `runtime`, `entry_point` may be sent. `display_name` is the optional free-form UI label; send `null` to clear it and fall back to `name`. An empty body is rejected with 400.
- [Delete app](https://puzzlet-9ba7bb98.mintlify.app/api-reference/apps/delete-app.md): Deletes an app. Cascades to all child rows via ON DELETE CASCADE (git_connection, git_branch, api_key, environment, etc.).
- [Get git connection status for an app](https://puzzlet-9ba7bb98.mintlify.app/api-reference/apps/get-git-connection-status-for-an-app.md): Returns the current git connection state. `connected: true` means a `git_connection` row exists (OAuth handshake completed). `repository` is null between OAuth-done and repo-picked.
- [Mint an OAuth authorization URL for git-provider connect](https://puzzlet-9ba7bb98.mintlify.app/api-reference/apps/mint-an-oauth-authorization-url-for-git-provider-connect.md): Returns a GitHub App install authorization URL plus a signed state token. Headless flow:
- [List repositories accessible to the app's git installation](https://puzzlet-9ba7bb98.mintlify.app/api-reference/apps/list-repositories-accessible-to-the-apps-git-installation.md): Returns repositories the linked GitHub App installation can see (the App's `/installation/repositories`).
- [List branches in a repository](https://puzzlet-9ba7bb98.mintlify.app/api-reference/apps/list-branches-in-a-repository.md): Returns the list of branch names for `repository` (passed as a query param because the value contains a slash). Use after `list-app-git-repositories` to populate a branch picker before linking.
- [Link a repository and branch to an app](https://puzzlet-9ba7bb98.mintlify.app/api-reference/apps/link-a-repository-and-branch-to-an-app.md): Persists the chosen repository + branch onto the app's existing git_connection. The next push to `branch` triggers the deploy webhook which materializes templates and datasets.
- [Clear the linked repository and branch](https://puzzlet-9ba7bb98.mintlify.app/api-reference/apps/clear-the-linked-repository-and-branch.md): Clears `git_connection.repository` and removes the `git_branch` row. The OAuth install is preserved so the user can re-link without re-clicking the install URL.
- [Service health](https://puzzlet-9ba7bb98.mintlify.app/api-reference/health/service-health.md): Check if the gateway service is running. Returns healthy if all required environment variables are configured.
- [Ingestion health](https://puzzlet-9ba7bb98.mintlify.app/api-reference/health/ingestion-health.md): Check the health of the trace ingestion pipeline and its dependencies.
- [Files health](https://puzzlet-9ba7bb98.mintlify.app/api-reference/health/files-health.md): Check the health of the files service and its dependencies.

## OpenAPI Specs

- [dashboard-openapi](https://puzzlet-9ba7bb98.mintlify.app/dashboard-openapi.yaml)
- [openapi](https://puzzlet-9ba7bb98.mintlify.app/openapi.yaml)

## Optional

- [GitHub](https://github.com/agentmark-ai/agentmark)
- [LinkedIn](https://www.linkedin.com/company/agentmark)