> ## Documentation Index > Fetch the complete documentation index at: https://docs.watchdog.no/llms.txt > Use this file to discover all available pages before exploring further. # Update an integration > Changes any of name, enabled, auto_sync, scope and credentials. Scope and credentials define what a sync reads, so they cannot change while a sync runs: cancel the run named by the 409 first. Changing them also cancels a running estimate. Send the ETag as If-Match: it is checked against the integration as it is when the change is applied, so of two edits made from the same ETag one succeeds and the other is 412. For a realtime provider, webhook subscriptions follow auto_sync once the change is saved; if the provider refuses, realtime.status shows it until the scheduled check repairs it. ## OpenAPI ````yaml /openapi-preview.json patch /v1/integrations/{id} openapi: 3.1.0 info: title: Watchdog API (preview) version: 1.0.0 description: >- Development preview for agreements, price items, document relationships, canonical invoices, alerts and alert topics, claims and attached alerts, shared entity activity and comments, Document uploads, invoice imports, explicit invoice-agreement matching, and workflow runs. This contract is under development and is not served by api.watchdog.no. Request bodies are limited to 2 MiB (2,097,152 bytes), including all JSON fields and line data, except POST /v1/support/contact which permits 32 MiB for base64 attachments. File bytes are uploaded directly to storage. The existing public REST service retains its separate contract. servers: - url: http://localhost:3500 description: Local development Worker security: [] paths: /v1/integrations/{id}: patch: tags: - Integrations summary: Update an integration description: >- Changes any of name, enabled, auto_sync, scope and credentials. Scope and credentials define what a sync reads, so they cannot change while a sync runs: cancel the run named by the 409 first. Changing them also cancels a running estimate. Send the ETag as If-Match: it is checked against the integration as it is when the change is applied, so of two edits made from the same ETag one succeeds and the other is 412. For a realtime provider, webhook subscriptions follow auto_sync once the change is saved; if the provider refuses, realtime.status shows it until the scheduled check repairs it. operationId: updateIntegration parameters: - name: X-Organization-Id in: header required: false schema: type: string description: >- Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization. - schema: type: string format: uuid required: true name: id in: path - schema: type: string minLength: 1 maxLength: 4096 description: >- Optional strong ETag from the individual resource GET. A stale validator returns 412. required: false description: >- Optional strong ETag from the individual resource GET. A stale validator returns 412. name: if-match in: header requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/UpdateIntegration' responses: '200': description: Current resource. headers: X-Request-Id: schema: type: string required: true description: >- Request identifier for support and diagnostics; also included in error bodies. Cache-Control: schema: type: string enum: - private, no-store required: false description: >- Organization-scoped API responses must not be cached. May be absent for requests rejected before routing. X-RateLimit-Limit: schema: type: string example: '120' required: false description: >- Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit. ETag: schema: type: string description: Strong validator for this individual resource. required: true description: Strong validator for this individual resource. content: application/json: schema: $ref: '#/components/schemas/Integration' '400': description: >- Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes). headers: X-Request-Id: schema: type: string required: true description: >- Request identifier for support and diagnostics; also included in error bodies. Cache-Control: schema: type: string enum: - private, no-store required: false description: >- Organization-scoped API responses must not be cached. May be absent for requests rejected before routing. X-RateLimit-Limit: schema: type: string example: '120' required: false description: >- Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit. content: application/json: schema: $ref: '#/components/schemas/Error_validation_error' example: error: code: validation_error message: >- Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes). request_id: req_example '401': description: Missing or invalid bearer credential. headers: X-Request-Id: schema: type: string required: true description: >- Request identifier for support and diagnostics; also included in error bodies. Cache-Control: schema: type: string enum: - private, no-store required: false description: >- Organization-scoped API responses must not be cached. May be absent for requests rejected before routing. X-RateLimit-Limit: schema: type: string example: '120' required: false description: >- Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit. WWW-Authenticate: schema: type: string required: false description: Bearer authentication challenge, when supplied. content: application/json: schema: $ref: '#/components/schemas/Error_invalid_token' example: error: code: invalid_token message: Missing or invalid bearer credential. request_id: req_example '403': description: >- Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions. headers: X-Request-Id: schema: type: string required: true description: >- Request identifier for support and diagnostics; also included in error bodies. Cache-Control: schema: type: string enum: - private, no-store required: false description: >- Organization-scoped API responses must not be cached. May be absent for requests rejected before routing. X-RateLimit-Limit: schema: type: string example: '120' required: false description: >- Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit. content: application/json: schema: $ref: >- #/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required example: error: code: forbidden message: >- Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions. request_id: req_example '404': description: The resource does not exist in the current organization. headers: X-Request-Id: schema: type: string required: true description: >- Request identifier for support and diagnostics; also included in error bodies. Cache-Control: schema: type: string enum: - private, no-store required: false description: >- Organization-scoped API responses must not be cached. May be absent for requests rejected before routing. X-RateLimit-Limit: schema: type: string example: '120' required: false description: >- Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit. content: application/json: schema: $ref: '#/components/schemas/Error_not_found' example: error: code: not_found message: The resource does not exist in the current organization. request_id: req_example '409': description: >- A sync is running (workflow_run_id names it), auto_sync needs an enabled and tested integration, or the name is taken. headers: X-Request-Id: schema: type: string required: true description: >- Request identifier for support and diagnostics; also included in error bodies. Cache-Control: schema: type: string enum: - private, no-store required: false description: >- Organization-scoped API responses must not be cached. May be absent for requests rejected before routing. X-RateLimit-Limit: schema: type: string example: '120' required: false description: >- Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit. content: application/json: schema: $ref: >- #/components/schemas/Error_sync_in_progress_integration_not_syncable_conflict example: error: code: sync_in_progress message: >- A sync is running (workflow_run_id names it), auto_sync needs an enabled and tested integration, or the name is taken. request_id: req_example '412': description: >- The integration changed since the supplied ETag was read. Nothing was saved; retrieve it and reapply the change. headers: X-Request-Id: schema: type: string required: true description: >- Request identifier for support and diagnostics; also included in error bodies. Cache-Control: schema: type: string enum: - private, no-store required: false description: >- Organization-scoped API responses must not be cached. May be absent for requests rejected before routing. X-RateLimit-Limit: schema: type: string example: '120' required: false description: >- Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit. content: application/json: schema: $ref: '#/components/schemas/Error_precondition_failed' example: error: code: precondition_failed message: >- The integration changed since the supplied ETag was read. Nothing was saved; retrieve it and reapply the change. request_id: req_example '429': description: The IP or authenticated credential exceeded its request limit. headers: X-Request-Id: schema: type: string required: true description: >- Request identifier for support and diagnostics; also included in error bodies. Cache-Control: schema: type: string enum: - private, no-store required: false description: >- Organization-scoped API responses must not be cached. May be absent for requests rejected before routing. X-RateLimit-Limit: schema: type: string example: '120' required: false description: >- Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit. Retry-After: schema: type: string example: '60' required: true description: Seconds to wait before retrying the request. content: application/json: schema: $ref: '#/components/schemas/Error_rate_limit_exceeded' example: error: code: rate_limit_exceeded message: >- The IP or authenticated credential exceeded its request limit. request_id: req_example '500': description: >- Unexpected server failure. Include the request ID when contacting support. headers: X-Request-Id: schema: type: string required: true description: >- Request identifier for support and diagnostics; also included in error bodies. Cache-Control: schema: type: string enum: - private, no-store required: false description: >- Organization-scoped API responses must not be cached. May be absent for requests rejected before routing. X-RateLimit-Limit: schema: type: string example: '120' required: false description: >- Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit. content: application/json: schema: $ref: '#/components/schemas/Error_internal_error' example: error: code: internal_error message: >- Unexpected server failure. Include the request ID when contacting support. request_id: req_example '503': description: >- Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided. headers: X-Request-Id: schema: type: string required: true description: >- Request identifier for support and diagnostics; also included in error bodies. Cache-Control: schema: type: string enum: - private, no-store required: false description: >- Organization-scoped API responses must not be cached. May be absent for requests rejected before routing. X-RateLimit-Limit: schema: type: string example: '120' required: false description: >- Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit. Retry-After: schema: type: string example: '60' required: true description: Seconds to wait before retrying the request. content: application/json: schema: $ref: '#/components/schemas/Error_service_unavailable' example: error: code: service_unavailable message: >- Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided. request_id: req_example security: - ApiKeyBearer: [] - ClerkSessionBearer: [] components: schemas: UpdateIntegration: type: object properties: name: type: string minLength: 1 maxLength: 120 enabled: type: boolean auto_sync: type: boolean scope: $ref: '#/components/schemas/IntegrationScope' credentials: type: object additionalProperties: {} description: >- Merge patch: omitted fields keep their saved value and null clears an optional field. Changing credentials resets status to not_tested. additionalProperties: false Integration: type: object properties: id: type: string format: uuid provider: type: string name: type: string status: type: string enum: - connected - invalid_credentials - permission_denied - server_error - not_tested description: Result of the latest test or sync. not_tested until the first test. syncable: type: boolean description: Enabled and in a status that allows a sync to start. enabled: type: boolean auto_sync: type: boolean description: Nightly incremental sync, plus webhooks where supported. scope: $ref: '#/components/schemas/IntegrationScope' credentials: type: object properties: values: type: object additionalProperties: {} description: Saved values of fields that are not secret. secrets_set: type: array items: type: string description: Secret fields that have a saved value. required: - values - secrets_set description: Secrets are write-only and never returned to any role. realtime: type: object properties: supported: type: boolean status: type: string enum: - active - degraded - inactive required: - supported - status rate_limited_until: type: - string - 'null' format: date-time description: The provider asked Watchdog to pause requests until this time. last_successful_sync: type: - object - 'null' properties: started_at: type: string format: date-time trigger: type: string enum: - manual - scheduled required: - started_at - trigger description: Latest sync that completed with full coverage. active_sync_id: type: - string - 'null' format: uuid created_at: type: string format: date-time updated_at: type: string format: date-time required: - id - provider - name - status - syncable - enabled - auto_sync - scope - credentials - realtime - rate_limited_until - last_successful_sync - active_sync_id - created_at - updated_at Error_validation_error: type: object properties: error: type: object properties: code: type: string enum: - validation_error message: type: string request_id: type: string description: type: string details: type: array items: type: object properties: code: type: string field: type: string message: type: string required: - code - field - message maxItems: 20 workflow_run_id: type: string format: uuid import_id: type: string format: uuid existing_party: type: object properties: type: type: string enum: - supplier - recipient id: type: string format: uuid required: - type - id required: - code - message - request_id required: - error Error_invalid_token: type: object properties: error: type: object properties: code: type: string enum: - invalid_token message: type: string request_id: type: string description: type: string details: type: array items: type: object properties: code: type: string field: type: string message: type: string required: - code - field - message maxItems: 20 workflow_run_id: type: string format: uuid import_id: type: string format: uuid existing_party: type: object properties: type: type: string enum: - supplier - recipient id: type: string format: uuid required: - type - id required: - code - message - request_id required: - error Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required: type: object properties: error: type: object properties: code: type: string enum: - forbidden - token_disabled - organization_required - insufficient_role - mfa_required message: type: string request_id: type: string description: type: string details: type: array items: type: object properties: code: type: string field: type: string message: type: string required: - code - field - message maxItems: 20 workflow_run_id: type: string format: uuid import_id: type: string format: uuid existing_party: type: object properties: type: type: string enum: - supplier - recipient id: type: string format: uuid required: - type - id required: - code - message - request_id required: - error Error_not_found: type: object properties: error: type: object properties: code: type: string enum: - not_found message: type: string request_id: type: string description: type: string details: type: array items: type: object properties: code: type: string field: type: string message: type: string required: - code - field - message maxItems: 20 workflow_run_id: type: string format: uuid import_id: type: string format: uuid existing_party: type: object properties: type: type: string enum: - supplier - recipient id: type: string format: uuid required: - type - id required: - code - message - request_id required: - error Error_sync_in_progress_integration_not_syncable_conflict: type: object properties: error: type: object properties: code: type: string enum: - sync_in_progress - integration_not_syncable - conflict message: type: string request_id: type: string description: type: string details: type: array items: type: object properties: code: type: string field: type: string message: type: string required: - code - field - message maxItems: 20 workflow_run_id: type: string format: uuid import_id: type: string format: uuid existing_party: type: object properties: type: type: string enum: - supplier - recipient id: type: string format: uuid required: - type - id required: - code - message - request_id required: - error Error_precondition_failed: type: object properties: error: type: object properties: code: type: string enum: - precondition_failed message: type: string request_id: type: string description: type: string details: type: array items: type: object properties: code: type: string field: type: string message: type: string required: - code - field - message maxItems: 20 workflow_run_id: type: string format: uuid import_id: type: string format: uuid existing_party: type: object properties: type: type: string enum: - supplier - recipient id: type: string format: uuid required: - type - id required: - code - message - request_id required: - error Error_rate_limit_exceeded: type: object properties: error: type: object properties: code: type: string enum: - rate_limit_exceeded message: type: string request_id: type: string description: type: string details: type: array items: type: object properties: code: type: string field: type: string message: type: string required: - code - field - message maxItems: 20 workflow_run_id: type: string format: uuid import_id: type: string format: uuid existing_party: type: object properties: type: type: string enum: - supplier - recipient id: type: string format: uuid required: - type - id required: - code - message - request_id required: - error Error_internal_error: type: object properties: error: type: object properties: code: type: string enum: - internal_error message: type: string request_id: type: string description: type: string details: type: array items: type: object properties: code: type: string field: type: string message: type: string required: - code - field - message maxItems: 20 workflow_run_id: type: string format: uuid import_id: type: string format: uuid existing_party: type: object properties: type: type: string enum: - supplier - recipient id: type: string format: uuid required: - type - id required: - code - message - request_id required: - error Error_service_unavailable: type: object properties: error: type: object properties: code: type: string enum: - service_unavailable message: type: string request_id: type: string description: type: string details: type: array items: type: object properties: code: type: string field: type: string message: type: string required: - code - field - message maxItems: 20 workflow_run_id: type: string format: uuid import_id: type: string format: uuid existing_party: type: object properties: type: type: string enum: - supplier - recipient id: type: string format: uuid required: - type - id required: - code - message - request_id required: - error IntegrationScope: type: object properties: suppliers: type: object properties: mode: type: string enum: - all - include - exclude items: type: array items: type: object properties: id: type: string minLength: 1 maxLength: 255 name: type: string maxLength: 500 code: type: string maxLength: 255 group: type: object properties: kind: type: string enum: - vendor-sites prefixes: type: array items: type: string minLength: 1 maxLength: 255 minItems: 1 maxItems: 1000 site_count: type: integer exclusiveMinimum: 0 inactive_site_count: type: integer minimum: 0 required: - kind - prefixes - site_count - inactive_site_count description: >- Set when one supplier stands for several provider vendor sites. required: - id - name maxItems: 5000 include_unidentified: type: boolean description: >- With mode include or exclude, also read invoices whose supplier the provider does not identify. Omitted reads them. required: - mode - items additionalProperties: false companies: type: array items: type: object properties: id: type: string minLength: 1 maxLength: 255 name: type: string maxLength: 500 country_code: type: - string - 'null' maxLength: 10 accounting_currency_code: type: - string - 'null' maxLength: 10 required: - id - name maxItems: 1000 description: Provider companies to read. Empty or omitted reads every company. processing_statuses: type: array items: type: string minLength: 1 maxLength: 100 minItems: 1 maxItems: 50 path_globs: type: array items: type: string minLength: 1 maxLength: 256 maxItems: 20 module_company_codes: type: object properties: costinvoice: type: array items: type: string minLength: 1 maxLength: 100 maxItems: 50 purchaseorder: type: array items: type: string minLength: 1 maxLength: 100 maxItems: 50 additionalProperties: false securitySchemes: ApiKeyBearer: type: http scheme: bearer description: >- Personal API key. Send X-Organization-Id. The required cumulative level is listed in x-watchdog-permission. ClerkSessionBearer: type: http scheme: bearer description: Clerk session with an active organization. ````