{ "openapi": "3.1.0", "info": { "title": "Latitude API", "version": "1.0.0", "description": "The Latitude public API. Authenticate using an API key via the `Authorization: Bearer` header." }, "servers": [ { "url": "https://api.latitude.so", "description": "Production" } ], "components": { "securitySchemes": { "ApiKeyAuth": { "type": "http", "scheme": "bearer", "description": "Organization-scoped API key" } }, "schemas": { "HealthResponse": { "type": "object", "properties": { "service": { "type": "string", "enum": [ "api" ] }, "status": { "type": "string", "enum": [ "ok" ] } }, "required": [ "service", "status" ] }, "OAuthProtectedResourceMetadata": { "type": "object", "properties": { "resource": { "type": "string" }, "authorization_servers": { "type": "array", "items": { "type": "string" } } }, "required": [ "resource", "authorization_servers" ] }, "Project": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable project identifier (CUID2)." }, "organizationId": { "type": "string", "description": "Organization that owns this project." }, "name": { "type": "string", "description": "Human-readable name." }, "slug": { "type": "string", "description": "URL-safe slug. Set from `name` at creation; renaming never changes it. It can only be changed from the dashboard, not via the API." }, "settings": { "$ref": "#/components/schemas/ProjectSettings" }, "firstTraceAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp of the first ingested trace. `null` until the first trace lands." }, "deletedAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp at which the project was deleted. `null` while the project is active." }, "lastEditedAt": { "type": "string", "description": "ISO-8601 timestamp of the most recent name/settings edit." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp of creation." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp of the last metadata change." } }, "required": [ "id", "organizationId", "name", "slug", "settings", "firstTraceAt", "deletedAt", "lastEditedAt", "createdAt", "updatedAt" ] }, "ProjectSettings": { "type": [ "object", "null" ], "properties": { "keepMonitoring": { "type": "boolean", "description": "When `true`, the evaluation linked to an issue keeps running after the issue is resolved. When `false`, resolving the issue stops the evaluation. Defaults to `true` when omitted." }, "notifications": { "$ref": "#/components/schemas/NotificationsSetting" }, "escalation": { "$ref": "#/components/schemas/EscalationSetting" } }, "description": "Per-project settings overrides. `null` means inherit from the organization." }, "NotificationsSetting": { "type": "object", "properties": { "incidents": { "$ref": "#/components/schemas/IncidentNotificationsSetting" } }, "description": "Per-group project-level notification toggles. Today only `incidents` exists; future groups (wrapped reports, etc.) slot in alongside." }, "IncidentNotificationsSetting": { "type": "object", "properties": { "issue.new": { "type": "boolean", "description": "Send a notification when a new issue is discovered. Defaults to `true` when omitted." }, "issue.regressed": { "type": "boolean", "description": "Send a notification when a previously-resolved issue regresses. Defaults to `true` when omitted." }, "issue.escalating": { "type": "boolean", "description": "Send a notification when an active issue is escalating in volume or severity. Defaults to `true` when omitted." } }, "description": "Per-alert-kind opt-out for incident notifications." }, "EscalationSetting": { "type": "object", "properties": { "sensitivity": { "type": "integer", "minimum": 1, "maximum": 6, "description": "Sensitivity of the escalation detector, 1 (most sensitive, more incidents) to 6 (least sensitive, fewer incidents). Defaults to a balanced value when omitted." } }, "description": "Tuning parameters for the escalation detector. Affects detector behaviour regardless of whether notifications are enabled." }, "Error": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] }, "CreateProjectBody": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Human-readable name for the project. Must be unique within the organization." } }, "required": [ "name" ] }, "PaginatedProjects": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Project" }, "description": "Page of items, in the requested sort order." }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for fetching the next page. `null` when there are no more pages. Pass it back in `cursor` to continue." }, "hasMore": { "type": "boolean", "description": "`true` when there is at least one more page after this one." } }, "required": [ "items", "nextCursor", "hasMore" ] }, "UpdateProjectBody": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "New human-readable name. Renaming never changes the slug." }, "settings": { "allOf": [ { "$ref": "#/components/schemas/ProjectSettings" }, { "description": "Replace the project's settings overrides. Omit to leave settings untouched. To clear overrides entirely, edit via the web UI." } ] }, "flaggers": { "type": "object", "properties": { "frustration": { "type": "boolean" }, "nsfw": { "type": "boolean" }, "refusal": { "type": "boolean" }, "laziness": { "type": "boolean" }, "jailbreaking": { "type": "boolean" }, "forgetting": { "type": "boolean" }, "trashing": { "type": "boolean" }, "tool-call-errors": { "type": "boolean" }, "output-schema-validation": { "type": "boolean" }, "empty-response": { "type": "boolean" } }, "description": "Enable or disable specific flaggers for the project. Keys are flagger slugs; values are the new `enabled` state. Omitted slugs are left untouched." } } }, "ScoreResponse": { "anyOf": [ { "$ref": "#/components/schemas/CustomScoreResponse" }, { "$ref": "#/components/schemas/EvaluationScoreResponse" } ] }, "CustomScoreResponse": { "type": "object", "properties": { "id": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Stable score identifier." }, "organizationId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Organization that owns this score." }, "projectId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Project this score lives in." }, "sessionId": { "type": [ "string", "null" ], "maxLength": 128, "description": "Session id lifted from the trace, when set. `null` when the trace has no session." }, "traceId": { "type": [ "string", "null" ], "minLength": 32, "maxLength": 32, "description": "Identifier of the scored trace." }, "spanId": { "type": [ "string", "null" ], "minLength": 16, "maxLength": 16, "description": "Span the score pins to. Defaults to the trace's last LLM-completion span." }, "simulationId": { "type": [ "string", "null" ], "minLength": 24, "maxLength": 24, "description": "Simulation reference, if any." }, "issueId": { "type": [ "string", "null" ], "minLength": 24, "maxLength": 24, "description": "Issue this score contributes to, if any." }, "value": { "type": "number", "minimum": 0, "maximum": 1, "description": "Normalized score value in [0, 1]." }, "passed": { "type": "boolean", "description": "Whether the score marks the output as passing." }, "feedback": { "type": "string", "description": "Free-text feedback explaining the score." }, "error": { "type": [ "string", "null" ], "minLength": 1, "description": "Generation error text, when score generation itself errored. `null` for successful scores." }, "errored": { "type": "boolean", "description": "`true` when the score could not be generated successfully." }, "duration": { "type": "integer", "minimum": 0, "description": "Score generation duration in nanoseconds." }, "tokens": { "type": "integer", "minimum": 0, "description": "LLM tokens consumed generating the score." }, "cost": { "type": "integer", "minimum": 0, "description": "Score cost in microcents (1/1,000,000 of a USD)." }, "draftedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO-8601 timestamp while the score is awaiting human confirmation. `null` for published / system scores." }, "annotatorId": { "type": [ "string", "null" ], "minLength": 24, "maxLength": 24, "description": "User who authored the score, if any." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp at which the score was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp of the last metadata update." }, "source": { "type": "string", "enum": [ "custom" ], "description": "Discriminator. `\"custom\"` denotes a user-supplied score." }, "sourceId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "User-supplied tag identifying the score's origin (echoed from the request)." }, "metadata": { "type": "object", "additionalProperties": {}, "description": "Arbitrary user-supplied metadata persisted alongside the score." } }, "required": [ "id", "organizationId", "projectId", "sessionId", "traceId", "spanId", "simulationId", "issueId", "value", "passed", "feedback", "error", "errored", "duration", "tokens", "cost", "draftedAt", "annotatorId", "createdAt", "updatedAt", "source", "sourceId", "metadata" ] }, "EvaluationScoreResponse": { "type": "object", "properties": { "id": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Stable score identifier." }, "organizationId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Organization that owns this score." }, "projectId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Project this score lives in." }, "sessionId": { "type": [ "string", "null" ], "maxLength": 128, "description": "Session id lifted from the trace, when set. `null` when the trace has no session." }, "traceId": { "type": [ "string", "null" ], "minLength": 32, "maxLength": 32, "description": "Identifier of the scored trace." }, "spanId": { "type": [ "string", "null" ], "minLength": 16, "maxLength": 16, "description": "Span the score pins to. Defaults to the trace's last LLM-completion span." }, "simulationId": { "type": [ "string", "null" ], "minLength": 24, "maxLength": 24, "description": "Simulation reference, if any." }, "issueId": { "type": [ "string", "null" ], "minLength": 24, "maxLength": 24, "description": "Issue this score contributes to, if any." }, "value": { "type": "number", "minimum": 0, "maximum": 1, "description": "Normalized score value in [0, 1]." }, "passed": { "type": "boolean", "description": "Whether the score marks the output as passing." }, "feedback": { "type": "string", "description": "Free-text feedback explaining the score." }, "error": { "type": [ "string", "null" ], "minLength": 1, "description": "Generation error text, when score generation itself errored. `null` for successful scores." }, "errored": { "type": "boolean", "description": "`true` when the score could not be generated successfully." }, "duration": { "type": "integer", "minimum": 0, "description": "Score generation duration in nanoseconds." }, "tokens": { "type": "integer", "minimum": 0, "description": "LLM tokens consumed generating the score." }, "cost": { "type": "integer", "minimum": 0, "description": "Score cost in microcents (1/1,000,000 of a USD)." }, "draftedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO-8601 timestamp while the score is awaiting human confirmation. `null` for published / system scores." }, "annotatorId": { "type": [ "string", "null" ], "minLength": 24, "maxLength": 24, "description": "User who authored the score, if any." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp at which the score was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp of the last metadata update." }, "source": { "type": "string", "enum": [ "evaluation" ], "description": "Discriminator. `\"evaluation\"` denotes a platform-generated evaluation score." }, "sourceId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "CUID of the evaluation that produced this score." }, "metadata": { "$ref": "#/components/schemas/EvaluationScoreMetadata" } }, "required": [ "id", "organizationId", "projectId", "sessionId", "traceId", "spanId", "simulationId", "issueId", "value", "passed", "feedback", "error", "errored", "duration", "tokens", "cost", "draftedAt", "annotatorId", "createdAt", "updatedAt", "source", "sourceId", "metadata" ] }, "EvaluationScoreMetadata": { "type": "object", "properties": { "evaluationHash": { "type": "string", "description": "Hash of the evaluation script that produced this score; lets the platform track which version generated it." } }, "required": [ "evaluationHash" ], "description": "Evaluation-specific metadata." }, "CreateScoreBody": { "anyOf": [ { "$ref": "#/components/schemas/CreateCustomScoreBody" }, { "$ref": "#/components/schemas/CreateEvaluationScoreBody" } ] }, "CreateCustomScoreBody": { "type": "object", "properties": { "simulationId": { "type": [ "string", "null" ], "minLength": 24, "maxLength": 24, "default": null, "description": "Simulation this score is tied to, if any. `null` (default) when not part of a simulation." }, "value": { "type": "number", "minimum": 0, "maximum": 1, "description": "Normalized score value in [0, 1]. Higher = better." }, "passed": { "type": "boolean", "description": "Whether the scored output passes the evaluator's bar." }, "feedback": { "type": "string", "description": "Free-text feedback explaining the score." }, "error": { "type": [ "string", "null" ], "minLength": 1, "default": null, "description": "Generation error text, when score generation itself failed. `null` (default) for successful scores." }, "duration": { "type": "integer", "minimum": 0, "default": 0, "description": "Score generation duration in nanoseconds. `0` for externally-computed scores." }, "tokens": { "type": "integer", "minimum": 0, "default": 0, "description": "LLM tokens consumed generating the score, if any. `0` for externally-computed scores." }, "cost": { "type": "integer", "minimum": 0, "default": 0, "description": "Score cost in microcents (1/1,000,000 of a USD). `0` for externally-computed scores." }, "trace": { "$ref": "#/components/schemas/TraceRef" }, "sourceId": { "type": "string", "minLength": 1, "maxLength": 128, "description": "User-supplied tag identifying the score's origin (e.g. `\"prod-pipeline\"`, `\"qa-script-v2\"`)." }, "metadata": { "type": "object", "additionalProperties": {}, "default": {}, "description": "Arbitrary user-supplied metadata persisted alongside the score." }, "_evaluation": { "type": "boolean", "enum": [ false ], "default": false, "description": "Discriminator: omit (or `false`) for custom scores. Required `true` for evaluation scores." } }, "required": [ "value", "passed", "feedback", "trace", "sourceId" ] }, "TraceRef": { "oneOf": [ { "type": "object", "properties": { "by": { "type": "string", "enum": [ "id" ], "description": "Match a single trace by its identifier. Pair with `id`." }, "id": { "type": "string", "minLength": 32, "maxLength": 32, "description": "32-character trace identifier." } }, "required": [ "by", "id" ] }, { "type": "object", "properties": { "by": { "type": "string", "enum": [ "filters" ], "description": "Match a single trace by a filter set. Pair with `filters`; exactly one trace must match." }, "filters": { "$ref": "#/components/schemas/FilterSet" } }, "required": [ "by", "filters" ] } ], "description": "Target trace. Either an explicit id or a filter set matching exactly one trace." }, "FilterSet": { "type": "object", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/FilterCondition" } }, "description": "Filter set keyed by field name. Each entry holds an array of conditions ANDed together for that field; field-level groups are also ANDed across the set." }, "FilterCondition": { "type": "object", "properties": { "op": { "type": "string", "enum": [ "eq", "neq", "gt", "gte", "lt", "lte", "in", "notIn", "contains", "notContains", "gtePercentile" ], "description": "Comparison operator applied to the field's value (e.g. `eq`, `neq`, `in`). The full operator list lives in the API reference." }, "value": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": { "anyOf": [ { "type": "string" }, { "type": "number" } ] } } ], "description": "Right-hand value compared against the field. Arrays are required for `in` / `notIn`-style operators." } }, "required": [ "op", "value" ] }, "CreateEvaluationScoreBody": { "type": "object", "properties": { "simulationId": { "type": [ "string", "null" ], "minLength": 24, "maxLength": 24, "default": null, "description": "Simulation this score is tied to, if any. `null` (default) when not part of a simulation." }, "value": { "type": "number", "minimum": 0, "maximum": 1, "description": "Normalized score value in [0, 1]. Higher = better." }, "passed": { "type": "boolean", "description": "Whether the scored output passes the evaluator's bar." }, "feedback": { "type": "string", "description": "Free-text feedback explaining the score." }, "error": { "type": [ "string", "null" ], "minLength": 1, "default": null, "description": "Generation error text, when score generation itself failed. `null` (default) for successful scores." }, "duration": { "type": "integer", "minimum": 0, "default": 0, "description": "Score generation duration in nanoseconds. `0` for externally-computed scores." }, "tokens": { "type": "integer", "minimum": 0, "default": 0, "description": "LLM tokens consumed generating the score, if any. `0` for externally-computed scores." }, "cost": { "type": "integer", "minimum": 0, "default": 0, "description": "Score cost in microcents (1/1,000,000 of a USD). `0` for externally-computed scores." }, "trace": { "$ref": "#/components/schemas/TraceRef" }, "_evaluation": { "type": "boolean", "enum": [ true ], "description": "Discriminator: `true` flags the body as an evaluation score (internal); `false`/omit for custom." }, "sourceId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "CUID of the evaluation that produced this score." }, "metadata": { "$ref": "#/components/schemas/EvaluationScoreMetadata" } }, "required": [ "value", "passed", "feedback", "trace", "_evaluation", "sourceId", "metadata" ], "description": "Internal, don't use" }, "Annotation": { "type": "object", "properties": { "id": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Stable annotation identifier." }, "organizationId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Organization that owns this annotation." }, "projectId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Project this annotation lives in." }, "sessionId": { "type": [ "string", "null" ], "maxLength": 128, "description": "Session id lifted from the annotated trace. `null` when the trace has no session." }, "traceId": { "type": [ "string", "null" ], "minLength": 32, "maxLength": 32, "description": "Identifier of the annotated trace." }, "spanId": { "type": [ "string", "null" ], "minLength": 16, "maxLength": 16, "description": "Span the annotation pins to. Defaults to the trace's last LLM-completion span." }, "simulationId": { "type": [ "string", "null" ], "minLength": 24, "maxLength": 24, "description": "Simulation reference, if any." }, "issueId": { "type": [ "string", "null" ], "minLength": 24, "maxLength": 24, "description": "Issue this annotation contributes to, if any." }, "value": { "type": "number", "minimum": 0, "maximum": 1, "description": "Normalized score value in [0, 1]. Higher = better." }, "passed": { "type": "boolean", "description": "Whether the annotation marks the output as passing." }, "feedback": { "type": "string", "description": "Free-text feedback explaining the score." }, "error": { "type": [ "string", "null" ], "minLength": 1, "description": "Generation error text, when the annotation itself errored. `null` for successful annotations." }, "errored": { "type": "boolean", "description": "`true` when the annotation could not be generated successfully." }, "duration": { "type": "integer", "minimum": 0, "description": "Generation duration in nanoseconds. `0` for human annotations." }, "tokens": { "type": "integer", "minimum": 0, "description": "Total LLM tokens consumed generating the score. `0` for human annotations." }, "cost": { "type": "integer", "minimum": 0, "description": "Total LLM cost in microcents (1/1,000,000 USD). `0` for human annotations." }, "draftedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "ISO-8601 timestamp at which the annotation was drafted. `null` for published annotations." }, "annotatorId": { "type": [ "string", "null" ], "minLength": 24, "maxLength": 24, "description": "User who authored the annotation. `null` when not attributed to a user." }, "createdAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp at which the annotation was created." }, "updatedAt": { "type": "string", "format": "date-time", "description": "ISO-8601 timestamp of the last metadata update." }, "source": { "type": "string", "enum": [ "annotation" ], "description": "Always `\"annotation\"` for this shape." }, "sourceId": { "anyOf": [ { "type": "string", "enum": [ "UI", "API", "SYSTEM" ] }, { "type": "string", "minLength": 24, "maxLength": 24 } ], "description": "Origin marker. Sentinel `\"UI\"` / `\"API\"` / `\"SYSTEM\"` for drafts and automation, or an annotation-queue CUID for queue-authored rows." }, "metadata": { "$ref": "#/components/schemas/AnnotationMetadata" } }, "required": [ "id", "organizationId", "projectId", "sessionId", "traceId", "spanId", "simulationId", "issueId", "value", "passed", "feedback", "error", "errored", "duration", "tokens", "cost", "draftedAt", "annotatorId", "createdAt", "updatedAt", "source", "sourceId", "metadata" ] }, "AnnotationMetadata": { "type": "object", "properties": { "rawFeedback": { "type": "string", "description": "Original feedback text as written by the annotator, before any server-side enrichment." }, "messageIndex": { "type": "integer", "minimum": 0, "description": "0-based message index inside the conversation. Omit for conversation-level annotations." }, "partIndex": { "type": "integer", "minimum": 0, "description": "0-based index into the target message's `parts[]`. Requires `messageIndex`." }, "startOffset": { "type": "integer", "minimum": 0, "description": "Inclusive start offset for substring annotations. Must be paired with `endOffset` and `partIndex`." }, "endOffset": { "type": "integer", "minimum": 0, "description": "Exclusive end offset for substring annotations. Must be paired with `startOffset` and `partIndex`, and `>= startOffset`." }, "textFormat": { "type": "string", "enum": [ "pretty-json" ], "description": "UI-side text transform applied before the offsets were captured (e.g. `\"pretty-json\"`). Resolvers must apply the same transform before slicing." } }, "required": [ "rawFeedback" ], "description": "Annotation-specific metadata: `rawFeedback` plus a snapshot of the anchor at write time." }, "CreateAnnotationBody": { "type": "object", "properties": { "simulationId": { "type": [ "string", "null" ], "minLength": 24, "maxLength": 24, "default": null, "description": "Simulation this annotation is tied to, if any. `null` (default) when not part of a simulation." }, "issueId": { "type": [ "string", "null" ], "minLength": 24, "maxLength": 24, "default": null, "description": "Pre-selected issue this annotation belongs to. Leave `null` (default) to let the automatic issue-discovery pipeline route the annotation." }, "value": { "type": "number", "minimum": 0, "maximum": 1, "description": "Normalized score value in [0, 1]. Higher = better." }, "passed": { "type": "boolean", "description": "Whether the annotated output passes the reviewer's bar." }, "feedback": { "type": "string", "minLength": 1, "description": "Free-text feedback explaining the score. Surfaced alongside the trace." }, "anchor": { "$ref": "#/components/schemas/AnnotationAnchor" }, "trace": { "$ref": "#/components/schemas/TraceRef" } }, "required": [ "value", "passed", "feedback", "trace" ] }, "AnnotationAnchor": { "type": "object", "properties": { "messageIndex": { "type": "integer", "minimum": 0, "description": "0-based message index inside the conversation. Omit for conversation-level annotations." }, "partIndex": { "type": "integer", "minimum": 0, "description": "0-based index into the target message's `parts[]`. Requires `messageIndex`." }, "startOffset": { "type": "integer", "minimum": 0, "description": "Inclusive start offset for substring annotations. Must be paired with `endOffset` and `partIndex`." }, "endOffset": { "type": "integer", "minimum": 0, "description": "Exclusive end offset for substring annotations. Must be paired with `startOffset` and `partIndex`, and `>= startOffset`." }, "textFormat": { "type": "string", "enum": [ "pretty-json" ], "description": "UI-side text transform applied before the offsets were captured (e.g. `\"pretty-json\"`). Resolvers must apply the same transform before slicing." } }, "description": "Optional anchor pinning the annotation to a specific message / part / offset range inside the trace." }, "PaginatedTraces": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Trace" }, "description": "Page of items, in the requested sort order." }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for fetching the next page. `null` when there are no more pages. Pass it back in `cursor` to continue." }, "hasMore": { "type": "boolean", "description": "`true` when there is at least one more page after this one." } }, "required": [ "items", "nextCursor", "hasMore" ] }, "Trace": { "type": "object", "properties": { "organizationId": { "type": "string", "description": "Organization that owns this trace." }, "projectId": { "type": "string", "description": "Project this trace belongs to." }, "traceId": { "type": "string", "description": "32-character trace identifier." }, "spanCount": { "type": "integer", "minimum": 0, "description": "Total number of spans in the trace." }, "errorCount": { "type": "integer", "minimum": 0, "description": "Number of spans flagged with an error status." }, "startTime": { "type": "string", "description": "ISO-8601 timestamp of the trace's earliest span." }, "endTime": { "type": "string", "description": "ISO-8601 timestamp of the trace's latest span." }, "durationNs": { "type": "number", "description": "Wall-clock duration of the trace in nanoseconds." }, "timeToFirstTokenNs": { "type": "number", "description": "Nanoseconds from the start of the first LLM span to its first emitted token. `0` if not measured." }, "tokensInput": { "type": "number", "description": "Total input tokens across LLM spans." }, "tokensOutput": { "type": "number", "description": "Total output tokens across LLM spans." }, "tokensCacheRead": { "type": "number", "description": "Total tokens served from the provider's prompt cache." }, "tokensCacheCreate": { "type": "number", "description": "Total tokens written to the provider's prompt cache." }, "tokensReasoning": { "type": "number", "description": "Total reasoning tokens reported by the model." }, "tokensTotal": { "type": "number", "description": "Sum of all token counters." }, "costInputMicrocents": { "type": "number", "description": "Cost of input tokens in microcents (1/1,000,000 USD)." }, "costOutputMicrocents": { "type": "number", "description": "Cost of output tokens in microcents (1/1,000,000 USD)." }, "costTotalMicrocents": { "type": "number", "description": "Total cost in microcents (1/1,000,000 USD)." }, "sessionId": { "type": [ "string", "null" ], "description": "Conversation/session identifier set by the SDK. `null` when absent." }, "userId": { "type": [ "string", "null" ], "description": "End-user identifier set by the SDK. `null` when absent." }, "simulationId": { "type": [ "string", "null" ], "description": "CUID of the simulation that produced this trace. `null` when not a simulation." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Free-form tags attached at ingest time." }, "models": { "type": "array", "items": { "type": "string" }, "description": "Model identifiers seen across the trace's LLM spans." }, "providers": { "type": "array", "items": { "type": "string" }, "description": "LLM-provider identifiers seen across the trace's spans." }, "serviceNames": { "type": "array", "items": { "type": "string" }, "description": "OpenTelemetry `service.name` values seen in the trace." }, "rootSpanId": { "type": [ "string", "null" ], "description": "Identifier of the trace's root span. `null` when no root span has been ingested." }, "rootSpanName": { "type": [ "string", "null" ], "description": "`name` attribute of the root span. `null` when no root span has been ingested." }, "positiveAnnotationCount": { "type": "integer", "minimum": 0, "description": "Number of `passed = true` annotations attached to this trace." }, "negativeAnnotationCount": { "type": "integer", "minimum": 0, "description": "Number of `passed = false` annotations attached to this trace." } }, "required": [ "organizationId", "projectId", "traceId", "spanCount", "errorCount", "startTime", "endTime", "durationNs", "timeToFirstTokenNs", "tokensInput", "tokensOutput", "tokensCacheRead", "tokensCacheCreate", "tokensReasoning", "tokensTotal", "costInputMicrocents", "costOutputMicrocents", "costTotalMicrocents", "sessionId", "userId", "simulationId", "tags", "models", "providers", "serviceNames", "rootSpanId", "rootSpanName", "positiveAnnotationCount", "negativeAnnotationCount" ] }, "ListTracesBody": { "type": "object", "properties": { "cursor": { "type": "string", "description": "Opaque cursor returned in a previous response's `nextCursor`. Omit on the first page." }, "limit": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "Page size. Defaults to 50; max 200." }, "sortBy": { "type": "string", "enum": [ "relevance", "startTime", "endTime", "durationNs", "tokensTotal", "costTotalMicrocents" ], "default": "startTime", "description": "Field to sort by. Defaults to `startTime`. Pass `relevance` together with `query` to rank by semantic match (best match first, then most recent)." }, "sortDirection": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort direction. Defaults to `desc` (most recent first)." }, "query": { "type": "string", "maxLength": 500, "description": "Free-text semantic search across the trace's input and output messages. Combined with `filters` via AND." }, "filters": { "$ref": "#/components/schemas/FilterSet" } } }, "TraceAnalyticsResponse": { "type": "object", "properties": { "traces": { "$ref": "#/components/schemas/TraceAnalyticsTraces" }, "cost": { "$ref": "#/components/schemas/TraceAnalyticsCost" }, "duration": { "$ref": "#/components/schemas/TraceAnalyticsDuration" }, "tokens": { "$ref": "#/components/schemas/TraceAnalyticsTokens" }, "timeToFirstToken": { "$ref": "#/components/schemas/TraceAnalyticsTimeToFirstToken" }, "spans": { "$ref": "#/components/schemas/TraceAnalyticsSpans" } }, "required": [ "traces", "cost", "duration", "tokens", "timeToFirstToken", "spans" ] }, "TraceAnalyticsTraces": { "type": "object", "properties": { "total": { "type": "number", "description": "Number of traces in the range." }, "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/TraceAnalyticsBucket" }, "description": "Number of traces per bucket." } }, "required": [ "total", "buckets" ] }, "TraceAnalyticsBucket": { "type": "object", "properties": { "bucket": { "type": "string", "description": "ISO-8601 UTC timestamp of the bucket's start." }, "value": { "type": "number", "description": "Metric value for this bucket." } }, "required": [ "bucket", "value" ] }, "TraceAnalyticsCost": { "type": "object", "properties": { "total": { "type": "number", "description": "Total trace cost in USD." }, "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/TraceAnalyticsBucket" }, "description": "Trace cost per bucket in USD." } }, "required": [ "total", "buckets" ] }, "TraceAnalyticsDuration": { "type": "object", "properties": { "median": { "type": "number", "description": "Median trace duration in seconds." }, "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/TraceAnalyticsBucket" }, "description": "Median trace duration per bucket in seconds." } }, "required": [ "median", "buckets" ] }, "TraceAnalyticsTokens": { "type": "object", "properties": { "total": { "type": "number", "description": "Total tokens across all LLM spans." }, "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/TraceAnalyticsBucket" }, "description": "Tokens per bucket across all LLM spans." } }, "required": [ "total", "buckets" ] }, "TraceAnalyticsTimeToFirstToken": { "type": "object", "properties": { "median": { "type": "number", "description": "Median time-to-first-token across LLM spans, in seconds." }, "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/TraceAnalyticsBucket" }, "description": "Median time-to-first-token per bucket, in seconds." } }, "required": [ "median", "buckets" ] }, "TraceAnalyticsSpans": { "type": "object", "properties": { "total": { "type": "number", "description": "Total number of spans." }, "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/TraceAnalyticsBucket" }, "description": "Number of spans per bucket." } }, "required": [ "total", "buckets" ] }, "TraceDetail": { "type": "object", "properties": { "organizationId": { "type": "string", "description": "Organization that owns this trace." }, "projectId": { "type": "string", "description": "Project this trace belongs to." }, "traceId": { "type": "string", "description": "32-character trace identifier." }, "spanCount": { "type": "integer", "minimum": 0, "description": "Total number of spans in the trace." }, "errorCount": { "type": "integer", "minimum": 0, "description": "Number of spans flagged with an error status." }, "startTime": { "type": "string", "description": "ISO-8601 timestamp of the trace's earliest span." }, "endTime": { "type": "string", "description": "ISO-8601 timestamp of the trace's latest span." }, "durationNs": { "type": "number", "description": "Wall-clock duration of the trace in nanoseconds." }, "timeToFirstTokenNs": { "type": "number", "description": "Nanoseconds from the start of the first LLM span to its first emitted token. `0` if not measured." }, "tokensInput": { "type": "number", "description": "Total input tokens across LLM spans." }, "tokensOutput": { "type": "number", "description": "Total output tokens across LLM spans." }, "tokensCacheRead": { "type": "number", "description": "Total tokens served from the provider's prompt cache." }, "tokensCacheCreate": { "type": "number", "description": "Total tokens written to the provider's prompt cache." }, "tokensReasoning": { "type": "number", "description": "Total reasoning tokens reported by the model." }, "tokensTotal": { "type": "number", "description": "Sum of all token counters." }, "costInputMicrocents": { "type": "number", "description": "Cost of input tokens in microcents (1/1,000,000 USD)." }, "costOutputMicrocents": { "type": "number", "description": "Cost of output tokens in microcents (1/1,000,000 USD)." }, "costTotalMicrocents": { "type": "number", "description": "Total cost in microcents (1/1,000,000 USD)." }, "sessionId": { "type": [ "string", "null" ], "description": "Conversation/session identifier set by the SDK. `null` when absent." }, "userId": { "type": [ "string", "null" ], "description": "End-user identifier set by the SDK. `null` when absent." }, "simulationId": { "type": [ "string", "null" ], "description": "CUID of the simulation that produced this trace. `null` when not a simulation." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Free-form tags attached at ingest time." }, "models": { "type": "array", "items": { "type": "string" }, "description": "Model identifiers seen across the trace's LLM spans." }, "providers": { "type": "array", "items": { "type": "string" }, "description": "LLM-provider identifiers seen across the trace's spans." }, "serviceNames": { "type": "array", "items": { "type": "string" }, "description": "OpenTelemetry `service.name` values seen in the trace." }, "rootSpanId": { "type": [ "string", "null" ], "description": "Identifier of the trace's root span. `null` when no root span has been ingested." }, "rootSpanName": { "type": [ "string", "null" ], "description": "`name` attribute of the root span. `null` when no root span has been ingested." }, "positiveAnnotationCount": { "type": "integer", "minimum": 0, "description": "Number of `passed = true` annotations attached to this trace." }, "negativeAnnotationCount": { "type": "integer", "minimum": 0, "description": "Number of `passed = false` annotations attached to this trace." }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Free-form metadata attached at ingest time." }, "systemInstructions": { "$ref": "#/components/schemas/GenAISystem" }, "inputMessages": { "type": "array", "items": { "$ref": "#/components/schemas/GenAIMessage" }, "description": "Input messages sent into the first LLM span of the trace, in OpenTelemetry GenAI format." }, "outputMessages": { "type": "array", "items": { "$ref": "#/components/schemas/GenAIMessage" }, "description": "Output messages from the last LLM span of the trace, in OpenTelemetry GenAI format." }, "allMessages": { "type": "array", "items": { "$ref": "#/components/schemas/GenAIMessage" }, "description": "Full conversation view for the trace's final turn — the last span's input messages followed by its output messages, in OpenTelemetry GenAI format." } }, "required": [ "organizationId", "projectId", "traceId", "spanCount", "errorCount", "startTime", "endTime", "durationNs", "timeToFirstTokenNs", "tokensInput", "tokensOutput", "tokensCacheRead", "tokensCacheCreate", "tokensReasoning", "tokensTotal", "costInputMicrocents", "costOutputMicrocents", "costTotalMicrocents", "sessionId", "userId", "simulationId", "tags", "models", "providers", "serviceNames", "rootSpanId", "rootSpanName", "positiveAnnotationCount", "negativeAnnotationCount", "metadata", "systemInstructions", "inputMessages", "outputMessages", "allMessages" ] }, "GenAISystem": { "type": "array", "items": { "type": "object", "additionalProperties": {} }, "description": "System instructions in OpenTelemetry GenAI format — an array of part objects." }, "GenAIMessage": { "type": "object", "additionalProperties": {}, "description": "Message in OpenTelemetry GenAI format (`role` + content parts + optional tool calls)." }, "TraceSpans": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Span" }, "description": "All spans belonging to the trace, ordered by `startTime` ascending." } }, "required": [ "items" ] }, "Span": { "type": "object", "properties": { "organizationId": { "type": "string", "description": "Organization that owns this span." }, "projectId": { "type": "string", "description": "Project this span belongs to." }, "traceId": { "type": "string", "description": "Identifier of the trace this span belongs to." }, "spanId": { "type": "string", "description": "Stable span identifier within the trace." }, "parentSpanId": { "type": [ "string", "null" ], "description": "Identifier of the parent span. `null` for root spans." }, "sessionId": { "type": [ "string", "null" ], "description": "Conversation/session identifier set by the SDK. `null` when absent." }, "userId": { "type": [ "string", "null" ], "description": "End-user identifier set by the SDK. `null` when absent." }, "simulationId": { "type": [ "string", "null" ], "description": "CUID of the simulation that produced this span. `null` when not a simulation." }, "apiKeyId": { "type": [ "string", "null" ], "description": "Latitude API key used to ingest the span. `null` when ingested without an API key." }, "startTime": { "type": "string", "description": "ISO-8601 timestamp at which the span started." }, "endTime": { "type": "string", "description": "ISO-8601 timestamp at which the span ended." }, "name": { "type": "string", "description": "Span name (e.g. the entry-point function or route)." }, "serviceName": { "type": "string", "description": "OpenTelemetry `service.name` of the emitting service." }, "kind": { "type": "string", "enum": [ "unspecified", "internal", "server", "client", "producer", "consumer" ], "description": "OpenTelemetry span kind." }, "statusCode": { "type": "string", "enum": [ "unset", "ok", "error" ], "description": "OpenTelemetry span status code." }, "statusMessage": { "type": "string", "description": "OpenTelemetry status message. Empty when not set." }, "traceFlags": { "type": "number", "description": "OpenTelemetry trace flags bitfield." }, "traceState": { "type": "string", "description": "OpenTelemetry trace state (vendor-specific propagation). Empty when not set." }, "errorType": { "type": [ "string", "null" ], "description": "Error class/type label when the span errored. `null` for successful spans." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Free-form tags attached at ingest time." }, "operation": { "type": "string", "description": "GenAI operation category (e.g. `\"chat\"`, `\"embeddings\"`, `\"execute_tool\"`, `\"invoke_agent\"`) or a custom string for non-GenAI spans." }, "provider": { "type": [ "string", "null" ], "description": "LLM provider id. `null` for non-LLM spans." }, "model": { "type": [ "string", "null" ], "description": "Model id as requested. `null` for non-LLM spans." }, "responseModel": { "type": [ "string", "null" ], "description": "Model id reported by the provider's response. `null` for non-LLM spans." }, "tokensInput": { "type": "number", "description": "Input tokens consumed by this span." }, "tokensOutput": { "type": "number", "description": "Output tokens produced by this span." }, "tokensCacheRead": { "type": "number", "description": "Tokens served from the provider's prompt cache." }, "tokensCacheCreate": { "type": "number", "description": "Tokens written to the provider's prompt cache." }, "tokensReasoning": { "type": "number", "description": "Reasoning tokens reported by the model." }, "costInputMicrocents": { "type": "number", "description": "Cost of input tokens in microcents (1/1,000,000 USD)." }, "costOutputMicrocents": { "type": "number", "description": "Cost of output tokens in microcents (1/1,000,000 USD)." }, "costTotalMicrocents": { "type": "number", "description": "Total cost in microcents (1/1,000,000 USD)." }, "costIsEstimated": { "type": "boolean", "description": "`true` when the cost was derived from public pricing tables instead of the provider's bill." }, "timeToFirstTokenNs": { "type": "number", "description": "Nanoseconds from the start of the span to its first emitted token. `0` if not measured." }, "isStreaming": { "type": "boolean", "description": "`true` when the span was produced by a streaming LLM call." }, "responseId": { "type": [ "string", "null" ], "description": "Response identifier returned by the LLM. `null` when the provider didn't return one." }, "finishReasons": { "type": "array", "items": { "type": "string" }, "description": "Per-choice finish reasons reported by the LLM provider." }, "scopeName": { "type": "string", "description": "OpenTelemetry instrumentation scope name. Empty when not set." }, "scopeVersion": { "type": "string", "description": "OpenTelemetry instrumentation scope version. Empty when not set." }, "retentionDays": { "type": "integer", "exclusiveMinimum": 0, "description": "Per-span retention override in days. Omitted when the project default applies." }, "ingestedAt": { "type": "string", "description": "ISO-8601 timestamp at which Latitude received this span." } }, "required": [ "organizationId", "projectId", "traceId", "spanId", "parentSpanId", "sessionId", "userId", "simulationId", "apiKeyId", "startTime", "endTime", "name", "serviceName", "kind", "statusCode", "statusMessage", "traceFlags", "traceState", "errorType", "tags", "operation", "provider", "model", "responseModel", "tokensInput", "tokensOutput", "tokensCacheRead", "tokensCacheCreate", "tokensReasoning", "costInputMicrocents", "costOutputMicrocents", "costTotalMicrocents", "costIsEstimated", "timeToFirstTokenNs", "isStreaming", "responseId", "finishReasons", "scopeName", "scopeVersion", "ingestedAt" ] }, "SpanDetail": { "type": "object", "properties": { "organizationId": { "type": "string", "description": "Organization that owns this span." }, "projectId": { "type": "string", "description": "Project this span belongs to." }, "traceId": { "type": "string", "description": "Identifier of the trace this span belongs to." }, "spanId": { "type": "string", "description": "Stable span identifier within the trace." }, "parentSpanId": { "type": [ "string", "null" ], "description": "Identifier of the parent span. `null` for root spans." }, "sessionId": { "type": [ "string", "null" ], "description": "Conversation/session identifier set by the SDK. `null` when absent." }, "userId": { "type": [ "string", "null" ], "description": "End-user identifier set by the SDK. `null` when absent." }, "simulationId": { "type": [ "string", "null" ], "description": "CUID of the simulation that produced this span. `null` when not a simulation." }, "apiKeyId": { "type": [ "string", "null" ], "description": "Latitude API key used to ingest the span. `null` when ingested without an API key." }, "startTime": { "type": "string", "description": "ISO-8601 timestamp at which the span started." }, "endTime": { "type": "string", "description": "ISO-8601 timestamp at which the span ended." }, "name": { "type": "string", "description": "Span name (e.g. the entry-point function or route)." }, "serviceName": { "type": "string", "description": "OpenTelemetry `service.name` of the emitting service." }, "kind": { "type": "string", "enum": [ "unspecified", "internal", "server", "client", "producer", "consumer" ], "description": "OpenTelemetry span kind." }, "statusCode": { "type": "string", "enum": [ "unset", "ok", "error" ], "description": "OpenTelemetry span status code." }, "statusMessage": { "type": "string", "description": "OpenTelemetry status message. Empty when not set." }, "traceFlags": { "type": "number", "description": "OpenTelemetry trace flags bitfield." }, "traceState": { "type": "string", "description": "OpenTelemetry trace state (vendor-specific propagation). Empty when not set." }, "errorType": { "type": [ "string", "null" ], "description": "Error class/type label when the span errored. `null` for successful spans." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Free-form tags attached at ingest time." }, "operation": { "type": "string", "description": "GenAI operation category (e.g. `\"chat\"`, `\"embeddings\"`, `\"execute_tool\"`, `\"invoke_agent\"`) or a custom string for non-GenAI spans." }, "provider": { "type": [ "string", "null" ], "description": "LLM provider id. `null` for non-LLM spans." }, "model": { "type": [ "string", "null" ], "description": "Model id as requested. `null` for non-LLM spans." }, "responseModel": { "type": [ "string", "null" ], "description": "Model id reported by the provider's response. `null` for non-LLM spans." }, "tokensInput": { "type": "number", "description": "Input tokens consumed by this span." }, "tokensOutput": { "type": "number", "description": "Output tokens produced by this span." }, "tokensCacheRead": { "type": "number", "description": "Tokens served from the provider's prompt cache." }, "tokensCacheCreate": { "type": "number", "description": "Tokens written to the provider's prompt cache." }, "tokensReasoning": { "type": "number", "description": "Reasoning tokens reported by the model." }, "costInputMicrocents": { "type": "number", "description": "Cost of input tokens in microcents (1/1,000,000 USD)." }, "costOutputMicrocents": { "type": "number", "description": "Cost of output tokens in microcents (1/1,000,000 USD)." }, "costTotalMicrocents": { "type": "number", "description": "Total cost in microcents (1/1,000,000 USD)." }, "costIsEstimated": { "type": "boolean", "description": "`true` when the cost was derived from public pricing tables instead of the provider's bill." }, "timeToFirstTokenNs": { "type": "number", "description": "Nanoseconds from the start of the span to its first emitted token. `0` if not measured." }, "isStreaming": { "type": "boolean", "description": "`true` when the span was produced by a streaming LLM call." }, "responseId": { "type": [ "string", "null" ], "description": "Response identifier returned by the LLM. `null` when the provider didn't return one." }, "finishReasons": { "type": "array", "items": { "type": "string" }, "description": "Per-choice finish reasons reported by the LLM provider." }, "scopeName": { "type": "string", "description": "OpenTelemetry instrumentation scope name. Empty when not set." }, "scopeVersion": { "type": "string", "description": "OpenTelemetry instrumentation scope version. Empty when not set." }, "retentionDays": { "type": "integer", "exclusiveMinimum": 0, "description": "Per-span retention override in days. Omitted when the project default applies." }, "ingestedAt": { "type": "string", "description": "ISO-8601 timestamp at which Latitude received this span." }, "metadata": { "type": "object", "additionalProperties": { "type": "string" }, "description": "Free-form metadata attached at ingest time." }, "systemInstructions": { "$ref": "#/components/schemas/GenAISpanSystem" }, "inputMessages": { "type": "array", "items": { "$ref": "#/components/schemas/GenAISpanMessage" }, "description": "Input messages sent into this LLM span, in OpenTelemetry GenAI format." }, "outputMessages": { "type": "array", "items": { "$ref": "#/components/schemas/GenAISpanMessage" }, "description": "Output messages returned by this LLM span, in OpenTelemetry GenAI format." }, "toolDefinitions": { "type": "array", "items": { "$ref": "#/components/schemas/ToolDefinition" }, "description": "Tool/function definitions made available to the LLM for this span." }, "toolCallId": { "type": "string", "description": "Tool-call id this span answers. Empty when the span isn't an `execute_tool` span." }, "toolName": { "type": "string", "description": "Name of the executed tool. Empty when the span isn't an `execute_tool` span." }, "toolInput": { "type": "string", "description": "Stringified arguments passed to the tool. Empty when the span isn't an `execute_tool` span." }, "toolOutput": { "type": "string", "description": "Stringified tool output. Empty when the span isn't an `execute_tool` span." }, "attrString": { "type": "object", "additionalProperties": { "type": "string" }, "description": "OpenTelemetry attributes with string values." }, "attrInt": { "type": "object", "additionalProperties": { "type": "number" }, "description": "OpenTelemetry attributes with integer values." }, "attrFloat": { "type": "object", "additionalProperties": { "type": "number" }, "description": "OpenTelemetry attributes with floating-point values." }, "attrBool": { "type": "object", "additionalProperties": { "type": "boolean" }, "description": "OpenTelemetry attributes with boolean values." }, "resourceString": { "type": "object", "additionalProperties": { "type": "string" }, "description": "OpenTelemetry resource attributes captured at ingest." }, "eventsJson": { "type": "string", "description": "JSON-encoded OpenTelemetry events array. Empty when the span has no events." }, "linksJson": { "type": "string", "description": "JSON-encoded OpenTelemetry span-links array. Empty when the span has no links." } }, "required": [ "organizationId", "projectId", "traceId", "spanId", "parentSpanId", "sessionId", "userId", "simulationId", "apiKeyId", "startTime", "endTime", "name", "serviceName", "kind", "statusCode", "statusMessage", "traceFlags", "traceState", "errorType", "tags", "operation", "provider", "model", "responseModel", "tokensInput", "tokensOutput", "tokensCacheRead", "tokensCacheCreate", "tokensReasoning", "costInputMicrocents", "costOutputMicrocents", "costTotalMicrocents", "costIsEstimated", "timeToFirstTokenNs", "isStreaming", "responseId", "finishReasons", "scopeName", "scopeVersion", "ingestedAt", "metadata", "systemInstructions", "inputMessages", "outputMessages", "toolDefinitions", "toolCallId", "toolName", "toolInput", "toolOutput", "attrString", "attrInt", "attrFloat", "attrBool", "resourceString", "eventsJson", "linksJson" ] }, "GenAISpanSystem": { "type": "array", "items": { "type": "object", "additionalProperties": {} }, "description": "System instructions in OpenTelemetry GenAI format — an array of part objects." }, "GenAISpanMessage": { "type": "object", "additionalProperties": {}, "description": "Message in OpenTelemetry GenAI format (`role` + content parts + optional tool calls)." }, "ToolDefinition": { "type": "object", "properties": { "name": { "type": "string", "description": "Tool name as exposed to the LLM." }, "description": { "type": "string", "description": "Tool description as exposed to the LLM." }, "parameters": { "description": "JSON Schema for the tool's parameters, as provided by the caller." } }, "required": [ "name", "description" ] }, "PaginatedTraceAnnotations": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Annotation" }, "description": "Page of items, in the requested sort order." }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for fetching the next page. `null` when there are no more pages. Pass it back in `cursor` to continue." }, "hasMore": { "type": "boolean", "description": "`true` when there is at least one more page after this one." } }, "required": [ "items", "nextCursor", "hasMore" ] }, "ExportTracesResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "queued" ], "description": "Always `\"queued\"`. The CSV is built asynchronously and emailed to `recipient` when ready." } }, "required": [ "status" ] }, "ExportTracesBody": { "type": "object", "properties": { "traces": { "$ref": "#/components/schemas/TracesRef" }, "recipient": { "type": "string", "format": "email", "description": "Email address the export download link is sent to. Must belong to a member of the requesting organization — otherwise the request is rejected with 400." } }, "required": [ "traces", "recipient" ] }, "TracesRef": { "oneOf": [ { "type": "object", "properties": { "by": { "type": "string", "enum": [ "ids" ], "description": "Match an explicit list of traces by their identifiers. Pair with `ids`." }, "ids": { "type": "array", "items": { "type": "string", "minLength": 32, "maxLength": 32, "description": "32-character trace identifier." }, "minItems": 1, "description": "Non-empty list of trace identifiers." } }, "required": [ "by", "ids" ] }, { "type": "object", "properties": { "by": { "type": "string", "enum": [ "filters" ], "description": "Match every trace produced by a filter set. Pair with `filters`; result count is not bounded." }, "filters": { "$ref": "#/components/schemas/FilterSet" } }, "required": [ "by", "filters" ] } ], "description": "Which traces to include in the export — either explicit ids or a filter set." }, "PaginatedSavedSearches": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/SavedSearch" }, "description": "Page of items, in the requested sort order." }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for fetching the next page. `null` when there are no more pages. Pass it back in `cursor` to continue." }, "hasMore": { "type": "boolean", "description": "`true` when there is at least one more page after this one." } }, "required": [ "items", "nextCursor", "hasMore" ] }, "SavedSearch": { "type": "object", "properties": { "id": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Stable saved-search identifier." }, "organizationId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Organization that owns this saved search." }, "projectId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Project this saved search belongs to." }, "slug": { "type": "string", "description": "URL-safe slug derived from `name`. Regenerated when the name changes in a way that affects the slug." }, "name": { "type": "string", "description": "Human-readable name." }, "query": { "type": [ "string", "null" ], "description": "Free-text semantic query applied alongside `filters`. `null` when the search is filter-only. At least one of `query` or `filters` must be set." }, "filters": { "allOf": [ { "$ref": "#/components/schemas/FilterSet" }, { "description": "Structured filter set applied alongside `query`. Empty object means filter-free. At least one of `query` or `filters` must be set." } ] }, "deletedAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp at which the search was deleted. `null` while active." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp of creation." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp of the last update." } }, "required": [ "id", "organizationId", "projectId", "slug", "name", "query", "filters", "deletedAt", "createdAt", "updatedAt" ] }, "CreateSavedSearchBody": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256, "description": "Human-readable name. Used to derive the slug." }, "query": { "type": [ "string", "null" ], "maxLength": 500, "default": null, "description": "Free-text semantic query. `null` (default) when the search is filter-only. At least one of `query` or `filters` must be set." }, "filters": { "allOf": [ { "$ref": "#/components/schemas/FilterSet" }, { "description": "Structured filter set. Defaults to `{}` (no filters). At least one of `query` or `filters` must be set." } ] } }, "required": [ "name" ] }, "UpdateSavedSearchBody": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "maxLength": 256, "description": "New human-readable name. Triggers slug regeneration when the change affects the slug form (cosmetic edits like capitalization keep the URL stable)." }, "query": { "type": [ "string", "null" ], "maxLength": 500, "description": "Replace the free-text query. Pass `null` to clear it." }, "filters": { "allOf": [ { "$ref": "#/components/schemas/FilterSet" }, { "description": "Replace the structured filter set." } ] } } }, "PaginatedIssues": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Issue" }, "description": "Page of items, in the requested sort order." }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for fetching the next page. `null` when there are no more pages. Pass it back in `cursor` to continue." }, "hasMore": { "type": "boolean", "description": "`true` when there is at least one more page after this one." } }, "required": [ "items", "nextCursor", "hasMore" ] }, "Issue": { "type": "object", "properties": { "id": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Stable issue identifier." }, "organizationId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Organization that owns this issue." }, "projectId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Project this issue belongs to." }, "slug": { "type": "string", "description": "URL-safe slug derived from `name`. Unique within the project." }, "name": { "type": "string", "description": "Human-readable name." }, "description": { "type": "string", "description": "Description of the issue." }, "source": { "type": "string", "enum": [ "annotation", "flagger", "custom" ], "description": "Where the issue originated from." }, "states": { "type": "array", "items": { "type": "string", "enum": [ "new", "escalating", "ongoing", "resolved", "regressed", "ignored" ] }, "description": "Active lifecycle states. An issue may carry multiple states at once (e.g. `escalating` + `ongoing`)." }, "resolvedAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp at which the issue was resolved, or `null`." }, "ignoredAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp at which the issue was ignored, or `null`." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp of creation." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp of the last update." }, "trend": { "type": "array", "items": { "$ref": "#/components/schemas/IssueTrendBucket" }, "description": "Daily occurrence counts over the past 14 days." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags seen on the issue's occurrences." }, "firstSeenAt": { "type": "string", "description": "ISO-8601 timestamp of the earliest occurrence in the time window." }, "lastSeenAt": { "type": "string", "description": "ISO-8601 timestamp of the latest occurrence in the time window." }, "occurrences": { "type": "integer", "minimum": 0, "description": "Number of occurrences in the time window." }, "affectedTracesPercent": { "type": "number", "minimum": 0, "maximum": 1, "description": "Fraction of project traces affected by this issue in the time window, in `[0, 1]`." } }, "required": [ "id", "organizationId", "projectId", "slug", "name", "description", "source", "states", "resolvedAt", "ignoredAt", "createdAt", "updatedAt", "trend", "tags", "firstSeenAt", "lastSeenAt", "occurrences", "affectedTracesPercent" ] }, "IssueTrendBucket": { "type": "object", "properties": { "bucket": { "type": "string", "description": "UTC day bucket (`YYYY-MM-DD`)." }, "count": { "type": "integer", "minimum": 0, "description": "Number of occurrences within the bucket." } }, "required": [ "bucket", "count" ] }, "IssueAnalyticsResponse": { "type": "object", "properties": { "ongoing": { "$ref": "#/components/schemas/IssueAnalyticsOngoing" }, "new": { "$ref": "#/components/schemas/IssueAnalyticsNew" }, "escalating": { "$ref": "#/components/schemas/IssueAnalyticsEscalating" }, "regressed": { "$ref": "#/components/schemas/IssueAnalyticsRegressed" }, "resolved": { "$ref": "#/components/schemas/IssueAnalyticsResolved" }, "occurrences": { "$ref": "#/components/schemas/IssueAnalyticsOccurrences" } }, "required": [ "ongoing", "new", "escalating", "regressed", "resolved", "occurrences" ] }, "IssueAnalyticsOngoing": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0, "description": "Number of ongoing issues." } }, "required": [ "total" ] }, "IssueAnalyticsNew": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0, "description": "Number of new issues." } }, "required": [ "total" ] }, "IssueAnalyticsEscalating": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0, "description": "Number of escalating issues." } }, "required": [ "total" ] }, "IssueAnalyticsRegressed": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0, "description": "Number of regressed issues." } }, "required": [ "total" ] }, "IssueAnalyticsResolved": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0, "description": "Number of resolved issues." } }, "required": [ "total" ] }, "IssueAnalyticsOccurrences": { "type": "object", "properties": { "total": { "type": "integer", "minimum": 0, "description": "Number of issue occurrences in the range." }, "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/IssueAnalyticsBucket" }, "description": "Number of issue occurrences per bucket." } }, "required": [ "total", "buckets" ] }, "IssueAnalyticsBucket": { "type": "object", "properties": { "bucket": { "type": "string", "description": "ISO-8601 UTC timestamp of the bucket's start." }, "value": { "type": "integer", "minimum": 0, "description": "Number of occurrences in this bucket." } }, "required": [ "bucket", "value" ] }, "IssueDetail": { "type": "object", "properties": { "id": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Stable issue identifier." }, "organizationId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Organization that owns this issue." }, "projectId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Project this issue belongs to." }, "slug": { "type": "string", "description": "URL-safe slug derived from `name`. Unique within the project." }, "name": { "type": "string", "description": "Human-readable name." }, "description": { "type": "string", "description": "Description of the issue." }, "source": { "type": "string", "enum": [ "annotation", "flagger", "custom" ], "description": "Where the issue originated from." }, "states": { "type": "array", "items": { "type": "string", "enum": [ "new", "escalating", "ongoing", "resolved", "regressed", "ignored" ] }, "description": "Active lifecycle states. An issue may carry multiple states at once (e.g. `escalating` + `ongoing`)." }, "resolvedAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp at which the issue was resolved, or `null`." }, "ignoredAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp at which the issue was ignored, or `null`." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp of creation." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp of the last update." }, "trend": { "type": "array", "items": { "$ref": "#/components/schemas/IssueTrendBucket" }, "description": "Daily occurrence counts over the past 14 days." }, "tags": { "type": "array", "items": { "type": "string" }, "description": "Tags seen on the issue's occurrences." }, "firstSeenAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp of the earliest occurrence over the issue's lifetime, or `null` if none yet." }, "lastSeenAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp of the latest occurrence over the issue's lifetime, or `null` if none yet." }, "occurrences": { "type": "integer", "minimum": 0, "description": "Lifetime occurrence count." }, "affectedTracesPercent": { "type": "number", "minimum": 0, "maximum": 1, "description": "Lifetime fraction of project traces affected by this issue, in `[0, 1]`." }, "evaluations": { "type": "array", "items": { "$ref": "#/components/schemas/Evaluation" }, "description": "Active evaluations monitoring the issue. Archived and deleted evaluations are excluded." }, "monitoringState": { "$ref": "#/components/schemas/IssueMonitoringState" } }, "required": [ "id", "organizationId", "projectId", "slug", "name", "description", "source", "states", "resolvedAt", "ignoredAt", "createdAt", "updatedAt", "trend", "tags", "firstSeenAt", "lastSeenAt", "occurrences", "affectedTracesPercent", "evaluations", "monitoringState" ] }, "Evaluation": { "type": "object", "properties": { "id": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Stable evaluation identifier." }, "name": { "type": "string", "description": "Human-readable name." }, "description": { "type": "string", "description": "Generated description of the evaluation." }, "alignedAt": { "type": "string", "description": "ISO-8601 timestamp at which the evaluation was last realigned." }, "archivedAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp at which the evaluation was archived, or `null`." }, "deletedAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp at which the evaluation was deleted, or `null`." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp of creation." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp of the last update." }, "sampling": { "type": "number", "minimum": 0, "maximum": 100, "description": "Sampling rate as a percentage in `[0, 100]`. `0` means the evaluation is paused." }, "alignment": { "$ref": "#/components/schemas/EvaluationAlignmentMetrics" } }, "required": [ "id", "name", "description", "alignedAt", "archivedAt", "deletedAt", "createdAt", "updatedAt", "sampling", "alignment" ] }, "EvaluationAlignmentMetrics": { "type": "object", "properties": { "alignmentMetric": { "type": "number", "description": "Headline score that judges how well the evaluation tracks human annotations." }, "accuracy": { "type": "number", "description": "Accuracy: `(TP + TN) / total`." }, "precision": { "type": "number", "description": "Precision: `TP / (TP + FP)`." }, "recall": { "type": "number", "description": "Recall / sensitivity: `TP / (TP + FN)`." }, "specificity": { "type": "number", "description": "Specificity: `TN / (TN + FP)`." }, "trueness": { "type": "number", "description": "Mean of precision and negative predictive value." }, "f1": { "type": "number", "description": "F1 score: harmonic mean of precision and recall." }, "balancedAccuracy": { "type": "number", "description": "Balanced accuracy: mean of recall and specificity." }, "matthewsCorrelationCoefficient": { "type": "number", "description": "Matthews correlation coefficient, in `[-1, 1]`." } }, "required": [ "alignmentMetric", "accuracy", "precision", "recall", "specificity", "trueness", "f1", "balancedAccuracy", "matthewsCorrelationCoefficient" ], "description": "Alignment metrics computed from the evaluation's confusion matrix." }, "IssueMonitoringState": { "oneOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "automatic" ] } }, "required": [ "kind" ], "description": "The issue is automatically monitored by the system and does not need an evaluation." }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "idle" ] } }, "required": [ "kind" ], "description": "The issue is not currently being monitored." }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "generating" ] } }, "required": [ "kind" ], "description": "An evaluation is being generated for this issue. The issue has no active evaluation yet." }, { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "realigning" ] }, "evaluationId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Id of the evaluation currently being realigned." } }, "required": [ "kind", "evaluationId" ], "description": "An active evaluation is being realigned." } ], "description": "Whether the issue is currently being monitored: `automatic`, `idle`, `generating`, or `realigning`." }, "IssueHistogram": { "type": "object", "properties": { "buckets": { "type": "array", "items": { "$ref": "#/components/schemas/IssueHistogramBucket" }, "description": "One entry per 12-hour UTC-aligned bucket in the requested range, including empty buckets (`count: 0`)." } }, "required": [ "buckets" ] }, "IssueHistogramBucket": { "type": "object", "properties": { "bucket": { "type": "string", "description": "ISO-8601 UTC timestamp of the bucket's start." }, "count": { "type": "integer", "minimum": 0, "description": "Number of occurrences within the bucket." } }, "required": [ "bucket", "count" ] }, "IssuesLifecycleResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/IssueLifecycleItem" }, "description": "Per-issue result, in the order requested." } }, "required": [ "items" ] }, "IssueLifecycleItem": { "type": "object", "properties": { "issueId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Issue this entry applies to." }, "resolvedAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp at which the issue was resolved, or `null`." }, "ignoredAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp at which the issue was ignored, or `null`." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp of the last update." }, "changed": { "type": "boolean", "description": "`true` when this call changed the issue, `false` when it was already in that state." } }, "required": [ "issueId", "resolvedAt", "ignoredAt", "updatedAt", "changed" ] }, "ResolveIssuesBody": { "allOf": [ { "$ref": "#/components/schemas/IssuesLifecycleBody" }, { "type": "object", "properties": { "keepMonitoring": { "type": "boolean", "description": "When `true`, monitoring continues after the issues are resolved. When `false`, monitoring stops. Defaults to the project setting." } } } ] }, "IssuesLifecycleBody": { "type": "object", "properties": { "issueIds": { "type": "array", "items": { "type": "string", "minLength": 24, "maxLength": 24 }, "minItems": 1, "description": "Non-empty list of issue ids. Operations are idempotent — already-applied issues are unchanged." } }, "required": [ "issueIds" ] }, "MonitorIssueResponse": { "type": "object", "properties": { "jobId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Identifier of the monitor job." }, "evaluationId": { "type": [ "string", "null" ], "minLength": 24, "maxLength": 24, "description": "The id of the evaluation being realigned, or `null` when a brand-new evaluation is being generated." } }, "required": [ "jobId", "evaluationId" ] }, "ExportIssuesResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "queued" ], "description": "Always `\"queued\"`. The CSV is emailed to `recipient` when ready." } }, "required": [ "status" ] }, "ExportIssuesBody": { "type": "object", "properties": { "recipient": { "type": "string", "format": "email", "description": "Email address the download link is sent to. Must belong to a member of the requesting organization." }, "issueIds": { "type": "array", "items": { "type": "string", "minLength": 24, "maxLength": 24 }, "description": "Restrict the export to this subset of issues. Omit to export every issue in the project." }, "lifecycleGroup": { "type": "string", "enum": [ "active", "archived" ], "description": "`\"active\"` for unresolved/unignored issues; `\"archived\"` for the rest. Omit to include both." } }, "required": [ "recipient" ] }, "ListIncidentsResponse": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Incident" }, "description": "Incidents matching the filters, ordered by `startedAt` ascending." } }, "required": [ "items" ] }, "Incident": { "type": "object", "properties": { "id": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Stable incident identifier." }, "organizationId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Organization that owns this incident." }, "projectId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Project this incident belongs to." }, "sourceType": { "type": "string", "enum": [ "issue", "savedSearch" ], "description": "Kind of entity that triggered the incident. `issue` for issue-lifecycle incidents; `savedSearch` for incidents raised by a monitor watching a search." }, "sourceId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Id of the entity that triggered the incident (matches `sourceType`)." }, "kind": { "type": "string", "enum": [ "issue.new", "issue.regressed", "issue.escalating", "savedSearch.match", "savedSearch.threshold", "savedSearch.escalating" ], "description": "Reason the incident opened. `issue.new` fires when a new issue is discovered; `issue.regressed` when a resolved issue is detected again; `issue.escalating` when an ongoing issue is being detected more than expected. The `savedSearch.*` kinds are raised by monitors watching a search: `savedSearch.match` on each new matching trace, `savedSearch.threshold` when matching traces are detected above a configured threshold, and `savedSearch.escalating` when they stay above the threshold for a sustained window." }, "severity": { "type": "string", "enum": [ "low", "medium", "high" ], "description": "Severity bucket assigned to the incident: `low`, `medium`, or `high`." }, "startedAt": { "type": "string", "description": "ISO-8601 timestamp at which the incident opened." }, "endedAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp at which the incident closed, or `null` if still open." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp at which the incident row was created." } }, "required": [ "id", "organizationId", "projectId", "sourceType", "sourceId", "kind", "severity", "startedAt", "endedAt", "createdAt" ] }, "PaginatedDatasets": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Dataset" }, "description": "Page of items, in the requested sort order." }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for fetching the next page. `null` when there are no more pages. Pass it back in `cursor` to continue." }, "hasMore": { "type": "boolean", "description": "`true` when there is at least one more page after this one." } }, "required": [ "items", "nextCursor", "hasMore" ] }, "Dataset": { "type": "object", "properties": { "id": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Stable dataset identifier." }, "organizationId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Organization that owns this dataset." }, "projectId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Project this dataset belongs to." }, "slug": { "type": "string", "description": "URL-safe slug derived from `name`. Unique within the project." }, "name": { "type": "string", "description": "Human-readable name." }, "description": { "type": [ "string", "null" ], "description": "Free-form description, or `null` when not set." }, "version": { "type": "integer", "minimum": 0, "description": "Current dataset version." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp of creation." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp of the last update." } }, "required": [ "id", "organizationId", "projectId", "slug", "name", "description", "version", "createdAt", "updatedAt" ] }, "CreateDatasetBody": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Human-readable name. Used to derive the slug." }, "description": { "type": "string", "description": "Free-form description. Defaults to `null` when omitted or empty." } }, "required": [ "name" ] }, "UpdateDatasetBody": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "New human-readable name. Renaming regenerates the slug." }, "description": { "type": [ "string", "null" ], "description": "New description. Pass `null` to clear; omit to keep the current value." } } }, "PaginatedDatasetRows": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/DatasetRow" }, "description": "Page of items, in the requested sort order." }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for fetching the next page. `null` when there are no more pages. Pass it back in `cursor` to continue." }, "hasMore": { "type": "boolean", "description": "`true` when there is at least one more page after this one." } }, "required": [ "items", "nextCursor", "hasMore" ] }, "DatasetRow": { "type": "object", "properties": { "rowId": { "type": "string", "description": "Stable row identifier." }, "datasetId": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Dataset this row belongs to." }, "input": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": {} }, { "type": "object", "additionalProperties": {} } ], "description": "Free-form cell value: any JSON scalar, array, or object." }, "output": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": {} }, { "type": "object", "additionalProperties": {} } ], "description": "Free-form cell value: any JSON scalar, array, or object." }, "expectedOutput": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": {} }, { "type": "object", "additionalProperties": {} } ], "description": "The correct answer for this row. Curators fill this in by hand; it is not derived from `output`." }, "metadata": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": {} }, { "type": "object", "additionalProperties": {} } ], "description": "Free-form cell value: any JSON scalar, array, or object." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp at which the row was inserted." }, "version": { "type": "integer", "minimum": 0, "description": "Dataset version this row belongs to." } }, "required": [ "rowId", "datasetId", "input", "output", "expectedOutput", "metadata", "createdAt", "version" ] }, "InsertDatasetRowsResponse": { "type": "object", "properties": { "versionId": { "type": "string", "description": "New dataset version id." }, "version": { "type": "integer", "minimum": 0, "description": "New dataset version number." }, "rowIds": { "type": "array", "items": { "type": "string" }, "description": "Ids of the inserted rows." } }, "required": [ "versionId", "version", "rowIds" ] }, "InsertDatasetRowsBody": { "type": "object", "properties": { "rows": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string", "minLength": 1, "maxLength": 128, "description": "Optional client-supplied row id. Generated when omitted." }, "input": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": {} }, { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Row input cell." }, "output": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": {} }, { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Row output cell." }, "expectedOutput": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": {} }, { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Correct answer for this row. Filled in by curators; usually distinct from `output`." }, "metadata": { "anyOf": [ { "type": "string" }, { "type": "number" }, { "type": "boolean" }, { "type": "array", "items": {} }, { "type": "object", "additionalProperties": {} }, { "type": "null" } ], "description": "Row metadata cell." } }, "required": [ "input" ] }, "minItems": 1, "description": "Rows to insert." } }, "required": [ "rows" ] }, "DeleteDatasetRowsResponse": { "type": "object", "properties": { "versionId": { "type": [ "string", "null" ], "description": "New dataset version id, or `null` when nothing was deleted." }, "version": { "type": "integer", "minimum": 0, "description": "New dataset version number." }, "deletedCount": { "type": "integer", "minimum": 0, "description": "Number of rows removed." } }, "required": [ "versionId", "version" ] }, "DeleteDatasetRowsBody": { "type": "object", "properties": { "selection": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "selected" ] }, "rowIds": { "type": "array", "items": { "type": "string" }, "minItems": 1 } }, "required": [ "mode", "rowIds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all" ] } }, "required": [ "mode" ] }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "allExcept" ] }, "rowIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode", "rowIds" ] } ], "description": "Rows to delete." } }, "required": [ "selection" ] }, "ImportRowsFromTracesResponse": { "type": "object", "properties": { "versionId": { "type": "string", "description": "New dataset version id." }, "version": { "type": "integer", "minimum": 0, "description": "New dataset version number." }, "rowIds": { "type": "array", "items": { "type": "string" }, "description": "Ids of the inserted rows." } }, "required": [ "versionId", "version", "rowIds" ] }, "ImportRowsFromTracesBody": { "type": "object", "properties": { "traces": { "allOf": [ { "$ref": "#/components/schemas/TracesRef" }, { "description": "Which traces to import as rows — either explicit ids or a filter set." } ] } }, "required": [ "traces" ] }, "ExportDatasetRowsReadyResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "ready" ], "description": "Always `\"ready\"`. The CSV is available at `downloadUrl`." }, "downloadUrl": { "type": "string", "description": "Short-lived signed URL pointing to the CSV in object storage. Follow it with a plain HTTP GET." }, "filename": { "type": "string", "description": "Suggested filename for the downloaded CSV." }, "expiresAt": { "type": "string", "description": "ISO-8601 timestamp at which `downloadUrl` stops working." }, "rowCount": { "type": "integer", "minimum": 0, "description": "Number of rows included in the export." } }, "required": [ "status", "downloadUrl", "filename", "expiresAt", "rowCount" ] }, "ExportDatasetRowsQueuedResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "queued" ], "description": "Always `\"queued\"`. The CSV is emailed to `recipient` when ready." }, "recipient": { "type": "string", "format": "email", "description": "Email address the export download link will be sent to." }, "rowCount": { "type": "integer", "minimum": 0, "description": "Number of rows the export will produce." } }, "required": [ "status", "recipient", "rowCount" ] }, "ExportDatasetRowsTooLargeResponse": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "too_large" ], "description": "Always `\"too_large\"`. The export exceeds the synchronous threshold." }, "rowCount": { "type": "integer", "minimum": 0, "description": "Number of rows the export would have produced." }, "threshold": { "type": "integer", "exclusiveMinimum": 0, "description": "Maximum row count this endpoint will generate synchronously." }, "recommendedAction": { "type": "string", "description": "Instructions for the caller — typically an LLM — on how to recover: ask the end user for an email address and retry the same call with `recipient` set to it." } }, "required": [ "status", "rowCount", "threshold", "recommendedAction" ] }, "ExportDatasetRowsBody": { "type": "object", "properties": { "selection": { "oneOf": [ { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "selected" ] }, "rowIds": { "type": "array", "items": { "type": "string" }, "minItems": 1 } }, "required": [ "mode", "rowIds" ] }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "all" ] } }, "required": [ "mode" ] }, { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "allExcept" ] }, "rowIds": { "type": "array", "items": { "type": "string" } } }, "required": [ "mode", "rowIds" ] } ], "description": "Rows to export. Defaults to `{ mode: \"all\" }` when omitted." }, "recipient": { "type": "string", "format": "email", "description": "Email address to send the download link to when the export is too large for the synchronous path. Must belong to a member of the requesting organization. Ignored when the export fits the synchronous path; required for the async email flow." } } }, "ApiKey": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable API-key identifier." }, "organizationId": { "type": "string", "description": "Organization that owns this API key." }, "name": { "type": "string", "description": "Human-readable name." }, "token": { "type": "string", "description": "The full API key token. Returned by create / get / update — store it securely; treat it as a password." }, "lastUsedAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp of the most recent successful authentication. `null` until first use." }, "deletedAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp at which the key was revoked. `null` while the key is active." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp of creation." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp of the last metadata update (rename, revoke, last-used touch)." } }, "required": [ "id", "organizationId", "name", "token", "lastUsedAt", "deletedAt", "createdAt", "updatedAt" ] }, "CreateApiKeyBody": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "Human-readable name for the API key. Used to distinguish keys in the UI." } }, "required": [ "name" ] }, "ApiKeyList": { "type": "object", "properties": { "apiKeys": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyListItem" } } }, "required": [ "apiKeys" ] }, "ApiKeyListItem": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable API-key identifier." }, "organizationId": { "type": "string", "description": "Organization that owns this API key." }, "name": { "type": "string", "description": "Human-readable name." }, "token": { "type": "string", "description": "Masked token preview safe to display in lists. Use `GET /api-keys/{apiKeyId}` to retrieve the full token." }, "lastUsedAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp of the most recent successful authentication. `null` until first use." }, "deletedAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp at which the key was revoked. `null` while the key is active." }, "createdAt": { "type": "string", "description": "ISO-8601 timestamp of creation." }, "updatedAt": { "type": "string", "description": "ISO-8601 timestamp of the last metadata update." } }, "required": [ "id", "organizationId", "name", "token", "lastUsedAt", "deletedAt", "createdAt", "updatedAt" ] }, "UpdateApiKeyBody": { "type": "object", "properties": { "name": { "type": "string", "minLength": 1, "description": "New human-readable name for the API key." } }, "required": [ "name" ] }, "OAuthKeyList": { "type": "object", "properties": { "oauthKeys": { "type": "array", "items": { "$ref": "#/components/schemas/OAuthKey" } } }, "required": [ "oauthKeys" ] }, "OAuthKey": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable OAuth key identifier." }, "clientId": { "type": "string", "description": "Identifier of the OAuth client the key was issued to." }, "clientName": { "type": [ "string", "null" ], "description": "Display name of the OAuth client." }, "clientIcon": { "type": [ "string", "null" ], "description": "Icon URL of the OAuth client." }, "userId": { "type": "string", "description": "Identifier of the user the key belongs to." }, "userName": { "type": [ "string", "null" ], "description": "Display name of the user. `null` until the user completes onboarding." }, "userEmail": { "type": "string", "description": "Email of the user." }, "lastActivityAt": { "type": [ "string", "null" ], "description": "ISO-8601 timestamp of the last refresh on the key. `null` if the key has never been used." }, "connectedAt": { "type": "string", "description": "ISO-8601 timestamp at which the key was connected." }, "disabled": { "type": "boolean", "description": "Whether the key has been disabled." } }, "required": [ "id", "clientId", "clientName", "clientIcon", "userId", "userName", "userEmail", "lastActivityAt", "connectedAt", "disabled" ] }, "AccountResponse": { "type": "object", "properties": { "user": { "$ref": "#/components/schemas/AccountUser" }, "organization": { "$ref": "#/components/schemas/AccountOrganization" }, "role": { "type": [ "string", "null" ], "enum": [ "owner", "admin", "member", null ], "description": "Caller's role in the organization. `null` for API-key callers (no real user behind the credential)." } }, "required": [ "user", "organization", "role" ] }, "AccountUser": { "type": [ "object", "null" ], "properties": { "id": { "type": "string", "description": "Stable user identifier across the API." }, "email": { "type": "string", "description": "Verified email address of the authenticated user." }, "name": { "type": [ "string", "null" ], "description": "Display name, when set. `null` until the user completes onboarding." }, "image": { "type": [ "string", "null" ], "description": "Profile image URL, when set." } }, "required": [ "id", "email", "name", "image" ], "description": "The user the request is acting on behalf of. `null` for API-key callers — API keys are org-scoped, not user-scoped." }, "AccountOrganization": { "type": "object", "properties": { "id": { "type": "string", "description": "Stable organization identifier across the API." }, "name": { "type": "string", "description": "Human-readable organization name." }, "slug": { "type": "string", "description": "URL-safe slug. Regenerated when the organization is renamed — don't use it as a stable key." } }, "required": [ "id", "name", "slug" ], "description": "Organization the request is scoped to." }, "MemberList": { "type": "object", "properties": { "members": { "type": "array", "items": { "$ref": "#/components/schemas/Member" } } }, "required": [ "members" ] }, "Member": { "oneOf": [ { "$ref": "#/components/schemas/ActiveMember" }, { "$ref": "#/components/schemas/InvitedMember" } ], "discriminator": { "propertyName": "status", "mapping": { "active": "#/components/schemas/ActiveMember", "invited": "#/components/schemas/InvitedMember" } } }, "ActiveMember": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "active" ], "description": "Discriminator for confirmed members — the user has accepted their invitation and joined the org." }, "id": { "type": "string", "description": "Stable membership identifier. Use this to address the row in update/remove endpoints." }, "organizationId": { "type": "string", "description": "Organization this membership belongs to." }, "userId": { "type": "string", "description": "Identifier of the user the membership represents." }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ], "description": "Member's role within the organization." }, "name": { "type": [ "string", "null" ], "description": "Display name of the user. `null` if the user hasn't completed onboarding." }, "email": { "type": "string", "description": "User's email address, verified at signup." }, "image": { "type": [ "string", "null" ], "description": "User's profile image URL, when set." }, "joinedAt": { "type": "string", "description": "ISO-8601 timestamp at which the user joined the organization." } }, "required": [ "status", "id", "organizationId", "userId", "role", "name", "email", "image", "joinedAt" ] }, "InvitedMember": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "invited" ], "description": "Discriminator for pending invitations — the invitee hasn't accepted yet, so no user record exists." }, "id": { "type": "string", "description": "Stable invitation identifier. Distinct from membership ids." }, "organizationId": { "type": "string", "description": "Organization the invitation grants access to." }, "userId": { "type": "null", "description": "Always `null` — no user record exists until the invitation is accepted." }, "role": { "type": [ "string", "null" ], "enum": [ "owner", "admin", "member", null ], "description": "Role the invitee will get once they accept. `null` means the default (`member`)." }, "name": { "type": "null", "description": "Always `null` — no user record exists yet." }, "email": { "type": "string", "description": "Email address the invitation was sent to." }, "image": { "type": "null", "description": "Always `null` — no user record exists yet." }, "invitedAt": { "type": "string", "description": "ISO-8601 timestamp at which the invitation was created." }, "expiresAt": { "type": "string", "description": "ISO-8601 timestamp at which the invitation expires." }, "inviterId": { "type": "string", "description": "User id of the member who issued the invitation." } }, "required": [ "status", "id", "organizationId", "userId", "role", "name", "email", "image", "invitedAt", "expiresAt", "inviterId" ] }, "InviteMemberBody": { "type": "object", "properties": { "email": { "type": "string", "format": "email", "description": "Email address to invite. The invitee receives an accept link by email." }, "role": { "type": "string", "enum": [ "owner", "admin", "member" ], "description": "Role to grant on acceptance. Defaults to `member` when omitted." } }, "required": [ "email" ] }, "UpdateMemberRoleBody": { "type": "object", "properties": { "role": { "type": "string", "enum": [ "admin", "member" ], "description": "New role. Owners cannot be changed via this endpoint — owner-transfer happens on the web." } }, "required": [ "role" ] } }, "parameters": {} }, "paths": { "/health": { "get": { "operationId": "health.get", "tags": [ "Health" ], "summary": "Health check", "x-fern-ignore": true, "responses": { "200": { "description": "Service is healthy", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } } } } }, "/.well-known/oauth-protected-resource": { "get": { "operationId": "wellKnown.oauthProtectedResource", "tags": [ "Well-known" ], "summary": "OAuth protected resource metadata", "description": "RFC 9728 metadata document advertising the authorization server(s) trusted to issue access tokens for this API.", "x-fern-ignore": true, "responses": { "200": { "description": "Protected resource metadata", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthProtectedResourceMetadata" } } } } } } }, "/v1/projects": { "post": { "tags": [ "Projects" ], "x-fern-sdk-group-name": "projects", "x-fern-sdk-method-name": "create", "summary": "Create project", "description": "Creates a new project within the organization. The name must be unique within the org.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "createProject", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateProjectBody" } } } }, "responses": { "201": { "description": "Project created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "Projects" ], "x-fern-sdk-group-name": "projects", "x-fern-sdk-method-name": "list", "summary": "List projects", "description": "Returns every project in the organization. The response uses the standard paginated shape; the project list currently fits in a single page (`nextCursor` is always `null`).", "security": [ { "ApiKeyAuth": [] } ], "operationId": "listProjects", "responses": { "200": { "description": "List of projects", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedProjects" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}": { "get": { "tags": [ "Projects" ], "x-fern-sdk-group-name": "projects", "x-fern-sdk-method-name": "get", "summary": "Get project", "description": "Returns a single project by slug.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getProject", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" } ], "responses": { "200": { "description": "Project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Projects" ], "x-fern-sdk-group-name": "projects", "x-fern-sdk-method-name": "update", "summary": "Update project", "description": "Updates a project's name and/or settings. Renaming never changes the slug, and the slug cannot be changed via the API (only from the dashboard). Use `id` or `slug` as stable references.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "updateProject", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProjectBody" } } } }, "responses": { "200": { "description": "Updated project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Project" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Projects" ], "x-fern-sdk-group-name": "projects", "x-fern-sdk-method-name": "delete", "summary": "Delete project", "description": "Deletes a project by slug.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "deleteProject", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" } ], "responses": { "204": { "description": "Project deleted" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/scores": { "post": { "tags": [ "Scores" ], "x-fern-sdk-group-name": "scores", "x-fern-sdk-method-name": "create", "summary": "Create project score", "description": "Creates a score against a target trace. The trace is resolved by explicit id (`trace.by = \"id\"`) or by a filter set (`trace.by = \"filters\"`, exactly one match required). Annotations use the separate `/annotations` endpoint.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "createScore", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateScoreBody" } } } }, "responses": { "201": { "description": "Score created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScoreResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/annotations": { "post": { "tags": [ "Annotations" ], "x-fern-sdk-group-name": "annotations", "x-fern-sdk-method-name": "create", "summary": "Create project annotation", "description": "Creates a published annotation score against a target trace. The trace is resolved by explicit id (`trace.by = \"id\"`) or by a filter set (`trace.by = \"filters\"`, exactly one match required). When called with an OAuth token, the annotation is attributed to the authenticated user.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "createAnnotation", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateAnnotationBody" } } } }, "responses": { "201": { "description": "Annotation created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Annotation" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/traces/list": { "post": { "tags": [ "Traces" ], "x-fern-sdk-group-name": "traces", "x-fern-sdk-method-name": "list", "summary": "List project traces", "description": "Returns a cursor-paginated page of traces in the project. Combine `filters` with `query` (free-text semantic search) to narrow the result set. Trace list rows exclude per-message LLM content — use `getTrace` for the full conversation view.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "listTraces", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListTracesBody" } } } }, "responses": { "200": { "description": "Page of traces", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedTraces" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/traces/analytics": { "get": { "tags": [ "Traces" ], "x-fern-sdk-group-name": "traces", "x-fern-sdk-method-name": "analytics", "summary": "Get project trace analytics", "description": "Returns trace analytics for the project: a total (or median) per metric over the requested range, plus a per-bucket series for each metric. Buckets are 12-hour UTC-aligned. The range defaults to the trailing 7 days.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getTraceAnalytics", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "format": "date-time", "description": "Lower bound (inclusive) of the time range. Defaults to 7 days before `toIso`." }, "required": false, "description": "Lower bound (inclusive) of the time range. Defaults to 7 days before `toIso`.", "name": "fromIso", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Upper bound (inclusive) of the time range. Defaults to now." }, "required": false, "description": "Upper bound (inclusive) of the time range. Defaults to now.", "name": "toIso", "in": "query" } ], "responses": { "200": { "description": "Trace analytics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TraceAnalyticsResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/traces/{traceId}": { "get": { "tags": [ "Traces" ], "x-fern-sdk-group-name": "traces", "x-fern-sdk-method-name": "get", "summary": "Get project trace", "description": "Returns a single trace by id, including the captured system instructions and the conversation messages from the trace's last LLM-completion span.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getTrace", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "minLength": 32, "maxLength": 32, "description": "32-character trace identifier." }, "required": true, "description": "32-character trace identifier.", "name": "traceId", "in": "path" } ], "responses": { "200": { "description": "Trace detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TraceDetail" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/traces/{traceId}/spans": { "get": { "tags": [ "Traces" ], "x-fern-sdk-group-name": "traces", "x-fern-sdk-method-name": "listSpans", "summary": "List trace spans", "description": "Returns every span belonging to the trace, ordered by `startTime` ascending. Spans carry the OpenTelemetry envelope (kind, status, attributes, resource) plus Latitude's GenAI enrichment (tokens, cost, operation, provider, model). Per-message LLM content is excluded for size; use a span point-lookup for the conversation payload.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "listTraceSpans", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "minLength": 32, "maxLength": 32, "description": "32-character trace identifier." }, "required": true, "description": "32-character trace identifier.", "name": "traceId", "in": "path" } ], "responses": { "200": { "description": "Spans of the trace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TraceSpans" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/traces/{traceId}/spans/{spanId}": { "get": { "tags": [ "Traces" ], "x-fern-sdk-group-name": "traces", "x-fern-sdk-method-name": "getSpan", "summary": "Get trace span", "description": "Returns one span by id, including the LLM conversation (system instructions, input messages, output messages), tool data (definitions, call id, input, output), and the full OpenTelemetry payload (attributes, resource, events, links) that's excluded from the lighter list shape.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getTraceSpan", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "minLength": 32, "maxLength": 32, "description": "32-character trace identifier." }, "required": true, "description": "32-character trace identifier.", "name": "traceId", "in": "path" }, { "schema": { "type": "string", "minLength": 16, "maxLength": 16, "description": "16-character span identifier." }, "required": true, "description": "16-character span identifier.", "name": "spanId", "in": "path" } ], "responses": { "200": { "description": "Span detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SpanDetail" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/traces/{traceId}/annotations": { "get": { "tags": [ "Traces" ], "x-fern-sdk-group-name": "traces", "x-fern-sdk-method-name": "listAnnotations", "summary": "List trace annotations", "description": "Returns a cursor-paginated page of annotations pinned to the trace, including both published annotations and drafts.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "listTraceAnnotations", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "minLength": 32, "maxLength": 32, "description": "32-character trace identifier." }, "required": true, "description": "32-character trace identifier.", "name": "traceId", "in": "path" }, { "schema": { "type": "string", "description": "Opaque cursor returned in a previous response's `nextCursor`. Omit on the first page." }, "required": false, "description": "Opaque cursor returned in a previous response's `nextCursor`. Omit on the first page.", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "Page size. Defaults to 50; max 200." }, "required": false, "description": "Page size. Defaults to 50; max 200.", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Annotations of the trace", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedTraceAnnotations" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/traces/{traceId}/annotations/{annotationId}": { "get": { "tags": [ "Traces" ], "x-fern-sdk-group-name": "traces", "x-fern-sdk-method-name": "getAnnotation", "summary": "Get trace annotation", "description": "Returns one annotation by id pinned to the trace.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getTraceAnnotation", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "minLength": 32, "maxLength": 32, "description": "32-character trace identifier." }, "required": true, "description": "32-character trace identifier.", "name": "traceId", "in": "path" }, { "schema": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Stable annotation identifier." }, "required": true, "description": "Stable annotation identifier.", "name": "annotationId", "in": "path" } ], "responses": { "200": { "description": "Annotation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Annotation" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/traces/export": { "post": { "tags": [ "Traces" ], "x-fern-sdk-group-name": "traces", "x-fern-sdk-method-name": "export", "summary": "Export project traces (async)", "description": "Enqueues a CSV export of the traces matched by `traces`. The export runs asynchronously; a download link is emailed to `recipient` when the file is ready. The response returns immediately with `status = \"queued\"`. The recipient must already be a member of the requesting organization.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "exportTraces", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportTracesBody" } } } }, "responses": { "202": { "description": "Export enqueued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportTracesResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/searches": { "get": { "tags": [ "Saved Searches" ], "x-fern-sdk-group-name": "savedSearches", "x-fern-sdk-method-name": "list", "summary": "List saved searches", "description": "Returns every saved search in the project. The response uses the standard paginated shape; the saved-search list currently fits in a single page (`nextCursor` is always `null`).", "security": [ { "ApiKeyAuth": [] } ], "operationId": "listSavedSearches", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" } ], "responses": { "200": { "description": "List of saved searches", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedSavedSearches" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Saved Searches" ], "x-fern-sdk-group-name": "savedSearches", "x-fern-sdk-method-name": "create", "summary": "Create saved search", "description": "Creates a saved search within the project. At least one of `query` or `filters` must be set. The slug is derived from `name`. OAuth-authenticated only.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "createSavedSearch", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateSavedSearchBody" } } } }, "responses": { "201": { "description": "Saved search created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedSearch" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/searches/{searchSlug}": { "get": { "tags": [ "Saved Searches" ], "x-fern-sdk-group-name": "savedSearches", "x-fern-sdk-method-name": "get", "summary": "Get saved search", "description": "Returns a single saved search by slug.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getSavedSearch", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "description": "Saved-search slug (human-readable identifier within the project)." }, "required": true, "description": "Saved-search slug (human-readable identifier within the project).", "name": "searchSlug", "in": "path" } ], "responses": { "200": { "description": "Saved search", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedSearch" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Saved Searches" ], "x-fern-sdk-group-name": "savedSearches", "x-fern-sdk-method-name": "update", "summary": "Update saved search", "description": "Updates a saved search. Renaming may regenerate the slug — clients should re-read the response or rely on the `id` for stable references.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "updateSavedSearch", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "description": "Saved-search slug (human-readable identifier within the project)." }, "required": true, "description": "Saved-search slug (human-readable identifier within the project).", "name": "searchSlug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateSavedSearchBody" } } } }, "responses": { "200": { "description": "Updated saved search", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SavedSearch" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Saved Searches" ], "x-fern-sdk-group-name": "savedSearches", "x-fern-sdk-method-name": "delete", "summary": "Delete saved search", "description": "Deletes a saved search by slug.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "deleteSavedSearch", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "description": "Saved-search slug (human-readable identifier within the project)." }, "required": true, "description": "Saved-search slug (human-readable identifier within the project).", "name": "searchSlug", "in": "path" } ], "responses": { "204": { "description": "Saved search deleted" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/searches/{searchSlug}/traces": { "get": { "tags": [ "Saved Searches" ], "x-fern-sdk-group-name": "savedSearches", "x-fern-sdk-method-name": "listTraces", "summary": "List traces matching a saved search", "description": "Returns a cursor-paginated page of traces that match the saved search's `query` + `filters`. Each row uses the same `Trace` shape as `listTraces` — use the trace point-lookup endpoints (`getTrace`, `listTraceSpans`, `getTraceSpan`, `listTraceAnnotations`) to drill into individual traces.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "listSavedSearchTraces", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "description": "Saved-search slug (human-readable identifier within the project)." }, "required": true, "description": "Saved-search slug (human-readable identifier within the project).", "name": "searchSlug", "in": "path" }, { "schema": { "type": "string", "description": "Opaque cursor returned in a previous response's `nextCursor`. Omit on the first page." }, "required": false, "description": "Opaque cursor returned in a previous response's `nextCursor`. Omit on the first page.", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "Page size. Defaults to 50; max 200." }, "required": false, "description": "Page size. Defaults to 50; max 200.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "enum": [ "relevance", "startTime", "endTime", "durationNs", "tokensTotal", "costTotalMicrocents" ], "default": "startTime", "description": "Field to sort by. Defaults to `startTime`. Pass `relevance` to rank by semantic match against the saved search's query (best match first, then most recent)." }, "required": false, "description": "Field to sort by. Defaults to `startTime`. Pass `relevance` to rank by semantic match against the saved search's query (best match first, then most recent).", "name": "sortBy", "in": "query" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort direction. Defaults to `desc` (most recent first)." }, "required": false, "description": "Sort direction. Defaults to `desc` (most recent first).", "name": "sortDirection", "in": "query" } ], "responses": { "200": { "description": "Page of traces", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedTraces" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/issues": { "get": { "tags": [ "Issues" ], "x-fern-sdk-group-name": "issues", "x-fern-sdk-method-name": "list", "summary": "List project issues", "description": "Returns a cursor-paginated page of issues in the project. Each item includes lifecycle `states` plus time-window stats: `firstSeenAt`, `lastSeenAt`, `occurrences`, `affectedTracesPercent`, `trend`, and `tags`.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "listIssues", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "description": "Opaque cursor returned in a previous response's `nextCursor`. Omit on the first page." }, "required": false, "description": "Opaque cursor returned in a previous response's `nextCursor`. Omit on the first page.", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "Page size. Defaults to 50; max 200." }, "required": false, "description": "Page size. Defaults to 50; max 200.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Free-text semantic search across the issues' names and descriptions." }, "required": false, "description": "Free-text semantic search across the issues' names and descriptions.", "name": "query", "in": "query" }, { "schema": { "type": "string", "enum": [ "active", "archived" ], "description": "`\"active\"` for unresolved/unignored issues; `\"archived\"` for the rest. Omit to include both." }, "required": false, "description": "`\"active\"` for unresolved/unignored issues; `\"archived\"` for the rest. Omit to include both.", "name": "lifecycleGroup", "in": "query" }, { "schema": { "type": "string", "enum": [ "lastSeen", "occurrences", "state" ], "default": "lastSeen", "description": "Sort field. `lastSeen` orders by most recent occurrence; `occurrences` by total count in the time window; `state` by lifecycle priority." }, "required": false, "description": "Sort field. `lastSeen` orders by most recent occurrence; `occurrences` by total count in the time window; `state` by lifecycle priority.", "name": "sortBy", "in": "query" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort direction. Defaults to `desc`." }, "required": false, "description": "Sort direction. Defaults to `desc`.", "name": "sortDirection", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Lower bound (inclusive) of the time window. Defaults to ~6 days ago." }, "required": false, "description": "Lower bound (inclusive) of the time window. Defaults to ~6 days ago.", "name": "fromIso", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Upper bound (inclusive) of the time window. Defaults to now." }, "required": false, "description": "Upper bound (inclusive) of the time window. Defaults to now.", "name": "toIso", "in": "query" } ], "responses": { "200": { "description": "Page of issues", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedIssues" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/issues/analytics": { "get": { "tags": [ "Issues" ], "x-fern-sdk-group-name": "issues", "x-fern-sdk-method-name": "analytics", "summary": "Get project issue analytics", "description": "Returns issue analytics for the project: counts of ongoing, new, escalating, regressed, and resolved issues, plus total occurrences and a per-bucket occurrence series. Buckets are 12-hour UTC-aligned. The range defaults to the trailing 7 days.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getIssueAnalytics", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "format": "date-time", "description": "Lower bound (inclusive) of the time range. Defaults to 7 days before `toIso`." }, "required": false, "description": "Lower bound (inclusive) of the time range. Defaults to 7 days before `toIso`.", "name": "fromIso", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Upper bound (inclusive) of the time range. Defaults to now." }, "required": false, "description": "Upper bound (inclusive) of the time range. Defaults to now.", "name": "toIso", "in": "query" } ], "responses": { "200": { "description": "Issue analytics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssueAnalyticsResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/issues/{issueSlug}": { "get": { "tags": [ "Issues" ], "x-fern-sdk-group-name": "issues", "x-fern-sdk-method-name": "get", "summary": "Get project issue", "description": "Returns the full-history detail view of one issue: lifecycle `states`, lifetime activity stats (`firstSeenAt`, `lastSeenAt`, `occurrences`, `affectedTracesPercent`, `tags`), a 14-day occurrence `trend`, the active `evaluations` monitoring it, and the current `monitoringState`.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getIssue", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "description": "Issue slug." }, "required": true, "description": "Issue slug.", "name": "issueSlug", "in": "path" } ], "responses": { "200": { "description": "Issue", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssueDetail" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/issues/{issueSlug}/trend": { "get": { "tags": [ "Issues" ], "x-fern-sdk-group-name": "issues", "x-fern-sdk-method-name": "trend", "summary": "Get issue occurrence histogram", "description": "Returns the occurrence histogram for one issue over `[fromIso, toIso]`. The default range is the trailing 14 days. Buckets are 12-hour wide and UTC-aligned.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getIssueTrend", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "description": "Issue slug." }, "required": true, "description": "Issue slug.", "name": "issueSlug", "in": "path" }, { "schema": { "type": "string", "format": "date-time", "description": "Lower bound (inclusive). Defaults to ~14 days before `toIso`." }, "required": false, "description": "Lower bound (inclusive). Defaults to ~14 days before `toIso`.", "name": "fromIso", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Upper bound (inclusive). Defaults to now." }, "required": false, "description": "Upper bound (inclusive). Defaults to now.", "name": "toIso", "in": "query" } ], "responses": { "200": { "description": "Occurrence histogram", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssueHistogram" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/issues/{issueSlug}/traces": { "get": { "tags": [ "Issues" ], "x-fern-sdk-group-name": "issues", "x-fern-sdk-method-name": "listTraces", "summary": "List issue traces", "description": "Returns the page of distinct traces that contributed at least one occurrence of the issue, ordered by most recent activity first.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "listIssueTraces", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "description": "Issue slug." }, "required": true, "description": "Issue slug.", "name": "issueSlug", "in": "path" }, { "schema": { "type": "string", "description": "Opaque cursor returned in a previous response's `nextCursor`. Omit on the first page." }, "required": false, "description": "Opaque cursor returned in a previous response's `nextCursor`. Omit on the first page.", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "Page size. Defaults to 50; max 200." }, "required": false, "description": "Page size. Defaults to 50; max 200.", "name": "limit", "in": "query" } ], "responses": { "200": { "description": "Page of traces", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedTraces" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/issues/resolve": { "post": { "tags": [ "Issues" ], "x-fern-sdk-group-name": "issues", "x-fern-sdk-method-name": "resolve", "summary": "Resolve issues", "description": "Marks each issue in `issueIds` as resolved. When `keepMonitoring` is `false`, monitoring is also stopped for each resolved issue; when omitted, the project's default applies.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "resolveIssues", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResolveIssuesBody" } } } }, "responses": { "200": { "description": "Per-issue result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssuesLifecycleResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/issues/unresolve": { "post": { "tags": [ "Issues" ], "x-fern-sdk-group-name": "issues", "x-fern-sdk-method-name": "unresolve", "summary": "Unresolve issues", "description": "Reverts each issue in `issueIds` to the unresolved state.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "unresolveIssues", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssuesLifecycleBody" } } } }, "responses": { "200": { "description": "Per-issue result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssuesLifecycleResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/issues/ignore": { "post": { "tags": [ "Issues" ], "x-fern-sdk-group-name": "issues", "x-fern-sdk-method-name": "ignore", "summary": "Ignore issues", "description": "Marks each issue in `issueIds` as ignored. Monitoring is also stopped for each ignored issue.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "ignoreIssues", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssuesLifecycleBody" } } } }, "responses": { "200": { "description": "Per-issue result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssuesLifecycleResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/issues/unignore": { "post": { "tags": [ "Issues" ], "x-fern-sdk-group-name": "issues", "x-fern-sdk-method-name": "unignore", "summary": "Unignore issues", "description": "Reverts each issue in `issueIds` to a non-ignored state.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "unignoreIssues", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssuesLifecycleBody" } } } }, "responses": { "200": { "description": "Per-issue result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IssuesLifecycleResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/issues/{issueSlug}/monitor": { "post": { "tags": [ "Issues" ], "x-fern-sdk-group-name": "issues", "x-fern-sdk-method-name": "monitor", "summary": "Monitor issue", "description": "Starts (or realigns) monitoring for the issue. When the issue has no active evaluation, a new one is generated. When an active evaluation exists, the call realigns it. The work runs asynchronously and the response returns immediately. Returns 400 when monitoring is already in progress for this issue.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "monitorIssue", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "description": "Issue slug." }, "required": true, "description": "Issue slug.", "name": "issueSlug", "in": "path" } ], "responses": { "202": { "description": "Monitor job enqueued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MonitorIssueResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/issues/{issueSlug}/unmonitor": { "post": { "tags": [ "Issues" ], "x-fern-sdk-group-name": "issues", "x-fern-sdk-method-name": "unmonitor", "summary": "Unmonitor issue", "description": "Stops monitoring the issue. Idempotent — issues that aren't being monitored return 204 without changing anything.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "unmonitorIssue", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "description": "Issue slug." }, "required": true, "description": "Issue slug.", "name": "issueSlug", "in": "path" } ], "responses": { "204": { "description": "Issue unmonitored" } } } }, "/v1/projects/{projectSlug}/issues/export": { "post": { "tags": [ "Issues" ], "x-fern-sdk-group-name": "issues", "x-fern-sdk-method-name": "export", "summary": "Export project issues (async)", "description": "Enqueues an asynchronous CSV export. The response returns immediately; the download link is emailed to `recipient` when the file is ready. The recipient must be a member of the requesting organization.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "exportIssues", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportIssuesBody" } } } }, "responses": { "202": { "description": "Export enqueued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportIssuesResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/incidents": { "get": { "tags": [ "Incidents" ], "x-fern-sdk-group-name": "incidents", "x-fern-sdk-method-name": "list", "summary": "List project incidents", "description": "Returns incidents in the project, ordered from oldest to newest. The time window defaults to the trailing 7 days.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "listIncidents", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "format": "date-time", "description": "Lower bound (inclusive) of the time window. Returns incidents whose lifetime overlaps `[fromIso, toIso]`. Defaults to 7 days before `toIso`." }, "required": false, "description": "Lower bound (inclusive) of the time window. Returns incidents whose lifetime overlaps `[fromIso, toIso]`. Defaults to 7 days before `toIso`.", "name": "fromIso", "in": "query" }, { "schema": { "type": "string", "format": "date-time", "description": "Upper bound (inclusive) of the time window. Defaults to now." }, "required": false, "description": "Upper bound (inclusive) of the time window. Defaults to now.", "name": "toIso", "in": "query" }, { "schema": { "type": "array", "items": { "type": "string", "enum": [ "issue", "savedSearch" ] }, "description": "Restrict to incidents whose source type matches any value in this list." }, "required": false, "description": "Restrict to incidents whose source type matches any value in this list.", "name": "sourceTypes", "in": "query" }, { "schema": { "type": "string", "minLength": 24, "maxLength": 24, "description": "Restrict to incidents tied to a single source entity (e.g. one issue id)." }, "required": false, "description": "Restrict to incidents tied to a single source entity (e.g. one issue id).", "name": "sourceId", "in": "query" }, { "schema": { "type": "array", "items": { "type": "string", "enum": [ "issue.new", "issue.regressed", "issue.escalating", "savedSearch.match", "savedSearch.threshold", "savedSearch.escalating" ] }, "description": "Restrict to incidents whose kind matches any value in this list." }, "required": false, "description": "Restrict to incidents whose kind matches any value in this list.", "name": "kinds", "in": "query" }, { "schema": { "type": "array", "items": { "type": "string", "enum": [ "low", "medium", "high" ] }, "description": "Restrict to incidents whose severity matches any value in this list." }, "required": false, "description": "Restrict to incidents whose severity matches any value in this list.", "name": "severities", "in": "query" } ], "responses": { "200": { "description": "Matching incidents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListIncidentsResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/datasets": { "get": { "tags": [ "Datasets" ], "x-fern-sdk-group-name": "datasets", "x-fern-sdk-method-name": "list", "summary": "List project datasets", "description": "Returns a cursor-paginated page of datasets in the project.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "listDatasets", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "description": "Opaque cursor returned in a previous response's `nextCursor`. Omit on the first page." }, "required": false, "description": "Opaque cursor returned in a previous response's `nextCursor`. Omit on the first page.", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "Page size. Defaults to 50; max 200." }, "required": false, "description": "Page size. Defaults to 50; max 200.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "enum": [ "name", "updatedAt" ], "default": "updatedAt", "description": "Field to sort by. Defaults to `updatedAt`." }, "required": false, "description": "Field to sort by. Defaults to `updatedAt`.", "name": "sortBy", "in": "query" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort direction. Defaults to `desc`." }, "required": false, "description": "Sort direction. Defaults to `desc`.", "name": "sortDirection", "in": "query" } ], "responses": { "200": { "description": "Page of datasets", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedDatasets" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Datasets" ], "x-fern-sdk-group-name": "datasets", "x-fern-sdk-method-name": "create", "summary": "Create dataset", "description": "Creates an empty dataset in the project. The slug is derived from `name`.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "createDataset", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateDatasetBody" } } } }, "responses": { "201": { "description": "Created dataset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dataset" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/datasets/{datasetSlug}": { "get": { "tags": [ "Datasets" ], "x-fern-sdk-group-name": "datasets", "x-fern-sdk-method-name": "get", "summary": "Get project dataset", "description": "Returns one dataset by slug.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getDataset", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "description": "Dataset slug (human-readable identifier within the project)." }, "required": true, "description": "Dataset slug (human-readable identifier within the project).", "name": "datasetSlug", "in": "path" } ], "responses": { "200": { "description": "Dataset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dataset" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Datasets" ], "x-fern-sdk-group-name": "datasets", "x-fern-sdk-method-name": "update", "summary": "Update dataset", "description": "Updates a dataset's `name` and/or `description`. Renaming regenerates the slug — clients should re-read the response or rely on the `id` for stable references.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "updateDataset", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "description": "Dataset slug (human-readable identifier within the project)." }, "required": true, "description": "Dataset slug (human-readable identifier within the project).", "name": "datasetSlug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateDatasetBody" } } } }, "responses": { "200": { "description": "Updated dataset", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Dataset" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Datasets" ], "x-fern-sdk-group-name": "datasets", "x-fern-sdk-method-name": "delete", "summary": "Delete dataset", "description": "Deletes a dataset by slug.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "deleteDataset", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "description": "Dataset slug (human-readable identifier within the project)." }, "required": true, "description": "Dataset slug (human-readable identifier within the project).", "name": "datasetSlug", "in": "path" } ], "responses": { "204": { "description": "Dataset deleted" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/datasets/{datasetSlug}/rows": { "get": { "tags": [ "Datasets" ], "x-fern-sdk-group-name": "datasets", "x-fern-sdk-method-name": "listRows", "summary": "List dataset rows", "description": "Returns a cursor-paginated page of rows.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "listDatasetRows", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "description": "Dataset slug (human-readable identifier within the project)." }, "required": true, "description": "Dataset slug (human-readable identifier within the project).", "name": "datasetSlug", "in": "path" }, { "schema": { "type": "string", "description": "Opaque cursor returned in a previous response's `nextCursor`. Omit on the first page." }, "required": false, "description": "Opaque cursor returned in a previous response's `nextCursor`. Omit on the first page.", "name": "cursor", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50, "description": "Page size. Defaults to 50; max 200." }, "required": false, "description": "Page size. Defaults to 50; max 200.", "name": "limit", "in": "query" }, { "schema": { "type": "string", "minLength": 1, "maxLength": 500, "description": "Free-text search against row cells." }, "required": false, "description": "Free-text search against row cells.", "name": "search", "in": "query" }, { "schema": { "type": "string", "enum": [ "asc", "desc" ], "default": "desc", "description": "Sort direction on `createdAt`. Defaults to `desc` (newest first)." }, "required": false, "description": "Sort direction on `createdAt`. Defaults to `desc` (newest first).", "name": "sortDirection", "in": "query" } ], "responses": { "200": { "description": "Page of rows", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedDatasetRows" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Datasets" ], "x-fern-sdk-group-name": "datasets", "x-fern-sdk-method-name": "insertRows", "summary": "Insert dataset rows", "description": "Appends one or more rows to the dataset.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "insertDatasetRows", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "description": "Dataset slug (human-readable identifier within the project)." }, "required": true, "description": "Dataset slug (human-readable identifier within the project).", "name": "datasetSlug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsertDatasetRowsBody" } } } }, "responses": { "201": { "description": "Rows inserted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsertDatasetRowsResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Datasets" ], "x-fern-sdk-group-name": "datasets", "x-fern-sdk-method-name": "deleteRows", "summary": "Delete dataset rows", "description": "Deletes rows matching the supplied selection.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "deleteDatasetRows", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "description": "Dataset slug (human-readable identifier within the project)." }, "required": true, "description": "Dataset slug (human-readable identifier within the project).", "name": "datasetSlug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteDatasetRowsBody" } } } }, "responses": { "200": { "description": "Rows deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteDatasetRowsResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/datasets/{datasetSlug}/rows/import/traces": { "post": { "tags": [ "Datasets" ], "x-fern-sdk-group-name": "datasets", "x-fern-sdk-method-name": "importRowsFromTraces", "summary": "Import dataset rows from traces", "description": "Imports one row per trace matched by `traces`.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "importDatasetRowsFromTraces", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "description": "Dataset slug (human-readable identifier within the project)." }, "required": true, "description": "Dataset slug (human-readable identifier within the project).", "name": "datasetSlug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportRowsFromTracesBody" } } } }, "responses": { "201": { "description": "Rows imported", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportRowsFromTracesResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/projects/{projectSlug}/datasets/{datasetSlug}/rows/export": { "post": { "tags": [ "Datasets" ], "x-fern-sdk-group-name": "datasets", "x-fern-sdk-method-name": "exportRows", "summary": "Export dataset rows", "description": "Exports the selected rows as CSV. Returns one of three outcomes, discriminated by `status`:\n\n- `\"ready\"` — the export fit in the synchronous path. Body carries a short-lived signed `downloadUrl` the caller follows with a plain HTTP GET.\n- `\"queued\"` — the export was too large for the synchronous path AND a `recipient` was supplied. The CSV will be emailed to that address. The recipient must be a member of the requesting organization.\n- `\"too_large\"` — the export was too large for the synchronous path AND no `recipient` was supplied. Body includes a `recommendedAction` describing how to recover (typically: ask the user for an email and retry with `recipient` set).", "security": [ { "ApiKeyAuth": [] } ], "operationId": "exportDatasetRows", "parameters": [ { "schema": { "type": "string", "description": "Project slug (human-readable identifier)" }, "required": true, "description": "Project slug (human-readable identifier)", "name": "projectSlug", "in": "path" }, { "schema": { "type": "string", "description": "Dataset slug (human-readable identifier within the project)." }, "required": true, "description": "Dataset slug (human-readable identifier within the project).", "name": "datasetSlug", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportDatasetRowsBody" } } } }, "responses": { "200": { "description": "CSV ready at the signed URL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportDatasetRowsReadyResponse" } } } }, "202": { "description": "Export queued; download link will be emailed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportDatasetRowsQueuedResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Export exceeds the synchronous threshold and no `recipient` was provided", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExportDatasetRowsTooLargeResponse" } } } } } } }, "/v1/api-keys": { "post": { "tags": [ "API Keys" ], "x-fern-sdk-group-name": "apiKeys", "x-fern-sdk-method-name": "create", "summary": "Generate API key", "description": "Generates a new API key for the organization. The token is only returned once — store it securely.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "createApiKey", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyBody" } } } }, "responses": { "201": { "description": "API key generated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKey" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "get": { "tags": [ "API Keys" ], "x-fern-sdk-group-name": "apiKeys", "x-fern-sdk-method-name": "list", "summary": "List API keys", "description": "Returns all API keys for the organization. Tokens are not included in the list response.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "listApiKeys", "responses": { "200": { "description": "List of API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyList" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/api-keys/{apiKeyId}": { "get": { "tags": [ "API Keys" ], "x-fern-sdk-group-name": "apiKeys", "x-fern-sdk-method-name": "get", "summary": "Get API key", "description": "Returns a single API key including the full unmasked `token`. Useful for retrieving a stored token by id without rotating it.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getApiKey", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "API-key identifier." }, "required": true, "description": "API-key identifier.", "name": "apiKeyId", "in": "path" } ], "responses": { "200": { "description": "API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKey" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "API Keys" ], "x-fern-sdk-group-name": "apiKeys", "x-fern-sdk-method-name": "update", "summary": "Update API key", "description": "Renames an API key. The token itself is immutable — use create + revoke if you need a new value.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "updateApiKey", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "API-key identifier." }, "required": true, "description": "API-key identifier.", "name": "apiKeyId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateApiKeyBody" } } } }, "responses": { "200": { "description": "API key updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKey" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "API Keys" ], "x-fern-sdk-group-name": "apiKeys", "x-fern-sdk-method-name": "revoke", "summary": "Revoke API key", "description": "Revokes an API key.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "revokeApiKey", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "API-key identifier." }, "required": true, "description": "API-key identifier.", "name": "apiKeyId", "in": "path" } ], "responses": { "204": { "description": "API key revoked" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/oauth-keys": { "get": { "tags": [ "OAuth Keys" ], "x-fern-sdk-group-name": "oauthKeys", "x-fern-sdk-method-name": "list", "summary": "List OAuth keys", "description": "Returns every OAuth key (like MCP clients) connected to the organization.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "listOAuthKeys", "responses": { "200": { "description": "List of OAuth keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthKeyList" } } } } } } }, "/v1/oauth-keys/{oauthKeyId}": { "get": { "tags": [ "OAuth Keys" ], "x-fern-sdk-group-name": "oauthKeys", "x-fern-sdk-method-name": "get", "summary": "Get OAuth key", "description": "Returns a single OAuth key (like MCP clients) by id.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getOAuthKey", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "OAuth key identifier." }, "required": true, "description": "OAuth key identifier.", "name": "oauthKeyId", "in": "path" } ], "responses": { "200": { "description": "OAuth key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OAuthKey" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "OAuth Keys" ], "x-fern-sdk-group-name": "oauthKeys", "x-fern-sdk-method-name": "revoke", "summary": "Revoke OAuth key", "description": "Revokes an OAuth key (like MCP clients). The connected client immediately loses access.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "revokeOAuthKey", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "OAuth key identifier." }, "required": true, "description": "OAuth key identifier.", "name": "oauthKeyId", "in": "path" } ], "responses": { "204": { "description": "OAuth key revoked" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/account": { "get": { "tags": [ "Account" ], "x-fern-sdk-group-name": "account", "x-fern-sdk-method-name": "get", "summary": "Get account", "description": "Returns the caller's account snapshot: the organization the request is scoped to, plus the user record and their role when the request was made by a real user (OAuth). API-key callers receive `user: null` and `role: null` because API keys aren't tied to a specific user.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getAccount", "responses": { "200": { "description": "Account snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountResponse" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/members": { "get": { "tags": [ "Members" ], "x-fern-sdk-group-name": "members", "x-fern-sdk-method-name": "list", "summary": "List members", "description": "Returns every active member of the caller's organization with their role and user details.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "listMembers", "responses": { "200": { "description": "List of members", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MemberList" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "post": { "tags": [ "Members" ], "x-fern-sdk-group-name": "members", "x-fern-sdk-method-name": "invite", "summary": "Invite a member", "description": "Issues an invitation to join the caller's organization. The invitee receives an accept link by email and becomes a member once they accept. The response is the pending invitation record. Requires OAuth authentication (API-key callers can't act on behalf of a specific user).", "security": [ { "ApiKeyAuth": [] } ], "operationId": "inviteMember", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteMemberBody" } } } }, "responses": { "201": { "description": "Invitation created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InvitedMember" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/members/{memberId}": { "get": { "tags": [ "Members" ], "x-fern-sdk-group-name": "members", "x-fern-sdk-method-name": "get", "summary": "Get member", "description": "Returns a single member of the caller's organization, including their role and user details.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "getMember", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Membership identifier." }, "required": true, "description": "Membership identifier.", "name": "memberId", "in": "path" } ], "responses": { "200": { "description": "Member", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActiveMember" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "patch": { "tags": [ "Members" ], "x-fern-sdk-group-name": "members", "x-fern-sdk-method-name": "update", "summary": "Update a member", "description": "Updates a member of the caller's organization. Today only the role is mutable. The caller must be an admin or owner; owners cannot be demoted via this endpoint. Requires OAuth authentication.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "updateMember", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Membership identifier." }, "required": true, "description": "Membership identifier.", "name": "memberId", "in": "path" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateMemberRoleBody" } } } }, "responses": { "200": { "description": "Member with the updated role", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActiveMember" } } } }, "400": { "description": "Validation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } }, "delete": { "tags": [ "Members" ], "x-fern-sdk-group-name": "members", "x-fern-sdk-method-name": "remove", "summary": "Remove a member", "description": "Removes a member from the caller's organization. Self-removal and removing the organization owner are rejected — transfer ownership first. Requires OAuth authentication.", "security": [ { "ApiKeyAuth": [] } ], "operationId": "removeMember", "parameters": [ { "schema": { "type": "string", "minLength": 1, "description": "Membership identifier." }, "required": true, "description": "Membership identifier.", "name": "memberId", "in": "path" } ], "responses": { "204": { "description": "Member removed" }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "webhooks": {} }