> ## 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. # Upsert error recommendation > Creates or fully replaces the error's recommendation (an error has at most one). Full-replace semantics like the error update: every field is taken from this request, so omitting annotationID reopens a resolved recommendation (the linked annotation IS the resolution). Required API key permission: `observe:errors:write`. ## OpenAPI ````yaml /api-reference/openapi/observe.yaml put /observe/errors/{errorID}/recommendation 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: 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: ObserveAlert description: Authentication alert rules, instances and history. x-group: Alert management - name: ObserveAnnotation description: Annotation APIs (dated notes for analytics context) 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: 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/errors/{errorID}/recommendation: put: tags: - ObserveError summary: Upsert error recommendation description: >- Creates or fully replaces the error's recommendation (an error has at most one). Full-replace semantics like the error update: every field is taken from this request, so omitting annotationID reopens a resolved recommendation (the linked annotation IS the resolution). Required API key permission: `observe:errors:write`. operationId: ObserveErrorRecommendationUpsert parameters: - name: errorID in: path required: true description: Error ID (format `err-`). schema: type: string x-oapi-codegen-extra-tags: validate: required,id=err requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/observeErrorRecommendationUpsertReq' responses: '200': description: The stored recommendation. content: application/json: schema: $ref: '#/components/schemas/observeErrorRecommendation' default: $ref: '#/components/responses/error' security: - bearerAuth: - observe:errors:write components: schemas: observeErrorRecommendationUpsertReq: type: object required: - action - summary properties: action: type: string enum: - ignore - observe - fix description: Recommended handling of the error. x-oapi-codegen-extra-tags: validate: required,oneof=ignore observe fix summary: type: string description: One-line summary of the recommendation. x-oapi-codegen-extra-tags: validate: required,min=1,max=255 explanation: type: string description: What happens and why (root cause), as markdown. x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=16384 reproduction: type: string description: Preconditions and steps to reproduce, as markdown. x-oapi-codegen-extra-tags: validate: omitempty,min=1,max=16384 fixDetails: type: string description: >- The recommended fix in detail, as markdown. Required when action is fix. x-oapi-codegen-extra-tags: validate: required_if=Action fix,omitempty,min=1,max=16384 source: type: string enum: - manual - ai-draft description: Provenance of the recommendation content; defaults to manual. x-oapi-codegen-extra-tags: validate: omitempty,oneof=manual ai-draft annotationID: type: string description: >- Annotation marking that the recommended action was carried out (format `ann-`) — linking it IS resolving the recommendation. Must exist in the project. Omitting it on a later upsert reopens (the annotation itself is untouched). x-oapi-codegen-extra-tags: validate: omitempty,id=ann observeErrorRecommendation: type: object description: > Curated guidance attached to an error (at most one per error): what the error is and how to reproduce it, the recommended handling (ignore / observe / fix), and — for fix — the fix in detail. Human-created like the error itself; classification never writes it. Free-text fields are markdown. required: - id - action - summary - source - createdMs - updatedMs properties: id: type: string description: Recommendation ID (format `erc-`). action: type: string enum: - ignore - observe - fix description: Recommended handling of the error. summary: type: string description: One-line summary of the recommendation. explanation: type: string description: What happens and why (root cause), as markdown. reproduction: type: string description: Preconditions and steps to reproduce, as markdown. fixDetails: type: string description: >- The recommended fix in detail, as markdown. Present when action is fix. source: type: string enum: - manual - ai-draft description: Provenance of the recommendation content. annotationID: type: string description: >- ID of the annotation marking that the recommended action was carried out (format `ann-`). Its presence IS the resolved state: the annotation's date is when, its description what was done. Absent while still open. The link survives the annotation's deletion; `annotation` is then absent. annotation: $ref: '#/components/schemas/observeAnnotation' assets: type: array maxItems: 100 description: > Media assets (screenshots, videos) attached to this recommendation, oldest first. Only confirmed (ready) uploads appear. View URLs are minted per asset via the downloadUrl endpoint. items: $ref: '#/components/schemas/observeAsset' 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. observeAnnotation: type: object required: - id - headline - dateMs - createdMs - updatedMs properties: id: type: string description: Annotation ID (format `ann-`). headline: type: string description: Short headline describing the annotation. description: type: string description: Optional longer description of the annotation. dateMs: description: The annotated point in time in milliseconds since epoch. type: integer format: int64 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. observeAsset: type: object description: > One user-uploaded media file (screenshot or video). The bytes live in a private object store; viewing goes through short-lived presigned URLs (see the downloadUrl endpoint), so this object carries metadata only. required: - id - fileName - contentType - sizeBytes - status - createdMs properties: id: type: string description: Asset ID (format `ast-`). fileName: type: string description: Original file name, for display. contentType: type: string description: >- MIME type (image/png, image/jpeg, image/webp, image/gif, video/mp4, video/webm, video/quicktime). sizeBytes: type: integer format: int64 description: Declared (and, once ready, verified) file size in bytes. status: type: string enum: - pending - ready description: Upload lifecycle — pending until the uploaded object was confirmed. createdMs: type: integer format: int64 description: Creation time in milliseconds since epoch. 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. ````