> ## Documentation Index > Fetch the complete documentation index at: https://docs.corbado.com/llms.txt > Use this file to discover all available pages before exploring further. # Create or update annotation by external key > Creates the project's annotation with this external key on the first call and replaces its content on later calls, so a writer that runs repeatedly (a release pipeline, a scheduled agent) keeps one annotation per key. Replacing follows the rules of `PUT /observe/annotations/{annotationID}`. The history records `created` or the kind of change. Concurrent first calls with the same key can answer `409`; retrying updates the annotation then created. Required API key permission: `observe:annotations:write`. ## OpenAPI ````yaml /api-reference/openapi/observe.yaml put /observe/annotations/byExternalKey/{externalKey} openapi: 3.1.1 info: version: 1.0.0 title: Corbado API description: > # Introduction This documentation gives an overview of all Corbado API calls to implement authentication observe. contact: name: Corbado team email: support@corbado.com url: https://www.corbado.com servers: - url: https://api.cloud.corbado.io/v1 security: - bearerAuth: [] tags: - name: ObserveFlow description: Flow search and related APIs x-group: Journeys and users - name: ObserveSubFlow description: Subflow search and related APIs x-group: Journeys and users - name: ObserveUser description: User search and related APIs x-group: Journeys and users - name: ObserveIdentifier description: Identifier search over submitted identifiers x-group: Journeys and users - name: ObserveClientEnv description: Client environment search APIs x-group: Journeys and users - name: ObserveTimeSeries description: Time series query APIs x-group: Metrics and funnels - name: ObserveFunnel description: Historical funnel metrics, dictionaries and coverage. x-group: Metrics and funnels - name: ObserveEvent description: Event ingestion and event feed APIs x-group: Events - name: ObserveError description: Named authentication errors and recommendations. x-group: Error management - name: ObserveErrorFlavour description: Error variants and their impact on authentication outcomes. x-group: Error management - name: ObserveFinding description: Curated findings that explain errors, their impact and who has to act. x-group: Error management - name: ObserveAlert description: Authentication alert rules, instances and history. x-group: Alert management - name: ObserveAnnotation description: >- Annotations, the project's memory (what is true about the data and how to read it) x-group: Annotations - name: ObserveTableExport description: Table export file listing and download APIs x-group: Data exports - name: ObserveTimeSeriesExport description: Time-series export generation and downloads. x-group: Data exports - name: ObserveDataExport description: Data export APIs x-group: User data - name: ObserveDataDeletionJob description: Data deletion job APIs x-group: User data - name: ObserveFlowTypeDefinition description: Flow type definitions used in authentication journeys. x-group: Catalogs and labels - name: ObserveCatalog description: Catalog APIs x-group: Catalogs and labels - name: OpenAPI description: Downloadable API specification - name: ProjectOperationExecution description: Project-scoped operation history and pipeline health - name: ObserveClassification description: Flow and subflow classification APIs - name: ObserveIntegrationStats description: Integration stats APIs - name: ObserveTimeSeriesPrecalculation description: Time series precalculation APIs - name: ObserveIDList x-group: Saved ID lists description: Stored ID-list selection APIs - name: ObserveDataContext description: Schema-loose data context APIs for agent and debugging tooling - name: ObserveData description: Observe data administration APIs - name: ObserveTrackingStats description: Tracking ingestion stats APIs - name: ObserveProbe description: Raw probe capture items (internal autocapture diagnostics) - name: ObserveTelemetry description: Raw SDK/integration diagnostic telemetry - name: ObserveExperiment x-group: Experiments description: Experiment catalog and run APIs - name: ObserveDataPolicy description: >- Project data policy catalogue (retention selected by the SDK's meta.dataPolicy code) - name: ObserveMetadata x-group: Metadata description: Authenticator metadata APIs (FIDO MDS + passkey AAGUID) - name: ObservePasskey x-group: Passkey analysis description: Observed passkey search and cohort analysis. paths: /observe/annotations/byExternalKey/{externalKey}: put: tags: - ObserveAnnotation summary: Create or update annotation by external key description: >- Creates the project's annotation with this external key on the first call and replaces its content on later calls, so a writer that runs repeatedly (a release pipeline, a scheduled agent) keeps one annotation per key. Replacing follows the rules of `PUT /observe/annotations/{annotationID}`. The history records `created` or the kind of change. Concurrent first calls with the same key can answer `409`; retrying updates the annotation then created. Required API key permission: `observe:annotations:write`. operationId: ObserveAnnotationUpsertByExternalKey parameters: - name: externalKey in: path required: true description: >- External key, unique per project. Lowercase letters, digits, `.`, `_` and `-`, at most 128 characters. example: release-2026.10.1 schema: type: string requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/observeAnnotationUpsertReq' responses: '200': description: Annotation created or updated. content: application/json: schema: $ref: '#/components/schemas/observeAnnotation' default: $ref: '#/components/responses/error' security: - bearerAuth: - observe:annotations:write components: schemas: observeAnnotationUpsertReq: type: object required: - kind - headline properties: kind: $ref: '#/components/schemas/observeAnnotationKind' description: Kind of the annotation. x-oapi-codegen-extra-tags: validate: >- required,oneof=event period setup interpretation constraint follow-up headline: type: string description: One line saying what the annotation records. x-oapi-codegen-extra-tags: validate: required,min=1,max=255 description: type: string description: Optional Markdown body with details. x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=10000 dateFrom: type: string description: >- Date in project time: `YYYY-MM`, `YYYY-MM-DD`, `YYYY-MM-DDTHH` or `YYYY-MM-DDTHH:MM:SS`; the format sets the precision. Required for events and periods, optional for follow-ups (not before), not allowed otherwise. pattern: ^\d{4}-\d{2}(-\d{2}(T\d{2}(:\d{2}:\d{2})?)?)?$ example: '2026-09-17T09:45:00' x-oapi-codegen-extra-tags: validate: omitempty,max=19 dateTo: type: string description: >- Last unit a period covers (inclusive), in the same format as `dateFrom`. Absent means ongoing. pattern: ^\d{4}-\d{2}(-\d{2}(T\d{2}(:\d{2}:\d{2})?)?)?$ example: '2026-09-21T18:00:00' x-oapi-codegen-extra-tags: validate: omitempty,max=19 approximate: type: boolean description: The date is not exact. Requires a date. status: $ref: '#/components/schemas/observeAnnotationStatus' description: Follow-ups only; defaults to `open`. x-oapi-codegen-extra-tags: validate: omitempty,oneof=open done effect: $ref: '#/components/schemas/observeAnnotationEffect' description: Events and periods only; defaults to `context`. x-oapi-codegen-extra-tags: validate: omitempty,oneof=context boundary degraded broken missing reading: type: string description: >- Events and periods only. The reading rule this date brings, e.g. "Compare identifier modality only within one side of this date". x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=2000 scope: $ref: '#/components/schemas/observeAnnotationScope' series: type: array description: >- Time series the annotation is mainly about, by name. Absent means all. maxItems: 50 items: type: string x-oapi-codegen-extra-tags: validate: omitempty,max=50,dive,min=1,max=255 display: type: boolean description: >- False hides the annotation from charts; documents always contain it. Defaults to true, and to false for source `system` unless an effect other than `context` is set. source: $ref: '#/components/schemas/observeAnnotationSource' description: >- Who wrote the annotation. Defaults to `manual` from the developer panel and `agent` from an API key. x-oapi-codegen-extra-tags: validate: omitempty,oneof=manual agent system evidence: type: array description: Kinds of evidence the annotation rests on. Absent means unverified. maxItems: 4 items: $ref: '#/components/schemas/observeAnnotationEvidence' x-oapi-codegen-extra-tags: validate: omitempty,max=4,dive,oneof=code trace data customer refs: type: array description: >- External references. Findings and annotations must exist in the project. maxItems: 50 items: $ref: '#/components/schemas/observeAnnotationRef' x-oapi-codegen-extra-tags: validate: omitempty,max=50,dive note: type: string description: >- Note stored in the annotation's history. Required when a follow-up is closed. x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=2000 observeAnnotation: type: object required: - id - kind - platform - headline - approximate - display - source - createdMs - updatedMs properties: id: type: string description: Annotation ID (format `ann-`). kind: $ref: '#/components/schemas/observeAnnotationKind' platform: type: boolean description: >- Platform annotation that applies to every project; managed by Corbado. headline: type: string description: One line saying what the annotation records. description: type: string description: Optional Markdown body with details. dateFrom: type: string description: >- Date as stated, in project time (UTC for platform annotations), in the format of its precision. dateTo: type: string description: >- Last unit a period covers (inclusive), in the same format. Absent on an ongoing period. datePrecision: $ref: '#/components/schemas/observeAnnotationDatePrecision' dateFromMs: type: integer format: int64 description: Start of `dateFrom` in milliseconds since epoch. dateToMs: type: integer format: int64 description: End of the span (exclusive) in milliseconds since epoch. approximate: type: boolean description: The date is not exact. status: $ref: '#/components/schemas/observeAnnotationStatus' effect: $ref: '#/components/schemas/observeAnnotationEffect' reading: type: string description: Reading rule this date brings (events and periods). scope: $ref: '#/components/schemas/observeAnnotationScope' series: type: array maxItems: 50 items: type: string display: type: boolean description: Shown on charts. source: $ref: '#/components/schemas/observeAnnotationSource' evidence: type: array maxItems: 4 items: $ref: '#/components/schemas/observeAnnotationEvidence' refs: type: array maxItems: 50 items: $ref: '#/components/schemas/observeAnnotationRef' externalKey: type: string createdMs: type: integer format: int64 description: Creation time in milliseconds since epoch. updatedMs: type: integer format: int64 description: Last update time in milliseconds since epoch. observeAnnotationKind: type: string enum: - event - period - setup - interpretation - constraint - follow-up description: >- What the annotation records: `event` something changed, `period` something held over a span, `setup` a fact about how the project works, `interpretation` how to read the data, `constraint` which data may be used, `follow-up` an unknown or open work. observeAnnotationStatus: type: string enum: - open - done description: Where a follow-up stands. observeAnnotationEffect: type: string enum: - context - boundary - degraded - broken - missing description: >- How an event or period changes the reading of the data: `context` background only, `boundary` compare only within one side, `degraded` data partly wrong, `broken` data wrong, `missing` no data. observeAnnotationScope: type: object description: >- Narrows what the annotation applies to, by time-series dimension. Absent means the whole project. additionalProperties: false properties: applicationID: type: string description: Application ID (format `app-`). x-oapi-codegen-extra-tags: validate: omitempty,id=app os: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=255 osVersion: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=255 browser: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=255 customTag1: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=255 customTag2: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=255 customTag3: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=255 customTag4: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=255 customTag5: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=255 customTag6: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=255 customTag7: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=255 customTag8: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=255 customTag9: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=255 customTag10: type: string x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=255 experimentRunID: type: string description: Experiment run ID (format `exr-`). x-oapi-codegen-extra-tags: validate: omitempty,id=exr experimentVariantID: type: string description: Experiment variant ID (format `exv-`). x-oapi-codegen-extra-tags: validate: omitempty,id=exv observeAnnotationSource: type: string enum: - manual - agent - system description: Who wrote the annotation or made a change. observeAnnotationEvidence: type: string enum: - code - trace - data - customer description: Kind of evidence an annotation rests on. observeAnnotationRef: type: object required: - type - value properties: type: type: string enum: - finding - annotation - project - commit - release - url description: What the reference points to. x-oapi-codegen-extra-tags: validate: required,oneof=finding annotation project commit release url value: type: string description: >- Finding, annotation or project ID, commit SHA, release name or absolute URL. x-oapi-codegen-extra-tags: validate: required,min=1,max=2000 observeAnnotationDatePrecision: type: string enum: - month - date - hour - datetime description: Unit the annotation's dates were stated in. errorRspV2: type: object required: - error properties: error: type: object required: - message properties: message: description: Error message type: string example: Validation failed details: description: Validation error details per field type: array items: type: object required: - field - message properties: field: description: Field name that failed validation type: string example: projectID message: description: Validation error message type: string example: required responses: error: description: Error content: application/json: schema: $ref: '#/components/schemas/errorRspV2' securitySchemes: bearerAuth: type: http scheme: bearer description: >- Use an Observe API key from the management console. The key selects the project and must grant the permission listed on the operation. Keep this key on your server. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.