InfraNest Integrations API

openapi: 3.2.0
info:
  title: InfraNest Integrations API
  description: Domains, DNS, cloud servers, certificates and uptime monitoring in one API, across the registrars, DNS hosts and clouds you already use, such as Cloudflare, Route 53, Hetzner and GoDaddy. Start in a free sandbox with sample data, use scoped tokens, try DNS changes as a dry run first, and retry safely with idempotency keys.
  version: 1.0.0
  x-logo:
    url: https://developers.infranest.io/logo.svg
    altText: InfraNest
  contact:
    name: InfraNest
    url: https://developers.infranest.io
  termsOfService: https://infranest.io/terms
servers:
- url: https://api.infranest.io
security:
- default: []
tags:
- name: Integrations
  description: ''
paths:
  /api/organizations/{organization_id}/integrations:
    get:
      summary: List connected integrations
      operationId: getApiOrganizationsOrganization_idIntegrations
      description: 'Everything the organization has connected — cloud, DNS, registrar and certificate accounts, alert destinations, outbound webhooks, automation connections and calendars — each with its status and health. A cloud, DNS, registrar or certificate account also carries `provider_status`: what the provider itself has wrong right now that concerns you — open incidents from its status page or feed, and failures InfraNest sees on its own calls to the provider across several workspaces — with `explains_failures` true when it is the provider’s API that is failing, so a failing account is the provider’s outage rather than its credential. It is null when nothing is wrong. Also returns summary counts and the integrations your plan does not include (`locks`).'
      parameters:
      - in: path
        name: organization_id
        required: true
        description: Your organization's ID.
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              example:
                connections:
                - id: 1
                  kind: provider
                  provider: hetzner
                  integration_key: hetzner
                  name: Hetzner — Production
                  categories:
                  - cloud
                  - dns
                  capabilities:
                  - cloud
                  - dns
                  counts:
                    servers: 6
                    zones: 2
                    domains: 0
                    certs: 1
                  suspended_capabilities: []
                  incident: null
                  auth_kind: api_token
                  enabled: true
                  status: connected
                  locked: false
                  health:
                    status: ok
                    success_rate: 100
                    total_calls: 97
                    last_error_at: null
                    last_success_at: '2026-01-15T12:00:00Z'
                  rate_limited: null
                  last_activity_at: '2026-01-15T12:00:00Z'
                  provider_status: null
                - id: 2
                  kind: provider
                  provider: cloudflare
                  integration_key: cloudflare
                  name: Cloudflare DNS
                  categories:
                  - dns
                  - domains
                  capabilities:
                  - dns
                  - registrar
                  counts:
                    servers: 0
                    zones: 5
                    domains: 0
                    certs: 1
                  suspended_capabilities: []
                  incident: null
                  auth_kind: api_token
                  enabled: true
                  status: connected
                  locked: false
                  health:
                    status: ok
                    success_rate: 100
                    total_calls: 49
                    last_error_at: null
                    last_success_at: '2026-01-15T12:00:00Z'
                  rate_limited: null
                  last_activity_at: '2026-01-15T12:00:00Z'
                  provider_status: null
                summary:
                  total: 25
                  connected: 19
                  degraded: 3
                  failing: 2
                  disabled: 1
                  issues: 5
                  locked: 0
                locks: []
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '429':
          $ref: '#/components/responses/Error429'
      tags:
      - Integrations
      x-infranest-scope: cloud.read
      x-infranest-token-writable: false
      x-infranest-module: integrations
      x-infranest-errors:
      - unauthenticated
      - scope_missing
      - wrong_organization
      - test_token_required
      - test_token_sandbox_only
      - permission_denied
      - not_found
      - rate_limited
  /api/organizations/{organization_id}/integrations/{provider}/activity/export:
    get:
      summary: Export integration activity as CSV
      operationId: streamThefilteredAPIActivityLogForAProviderAsACSVDownload
      description: Downloads every call logged for this integration as a CSV file, newest first. Takes the same `status`, `capability`, `direction`, `credential_id` and `search` filters as the activity list.
      parameters:
      - in: path
        name: organization_id
        required: true
        description: Your organization's ID.
        schema:
          type: integer
      - in: path
        name: provider
        required: true
        description: The provider.
        schema:
          type: string
      responses:
        '200':
          description: The integration's activity log as CSV.
          content:
            text/csv:
              schema:
                type: string
                format: binary
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '429':
          $ref: '#/components/responses/Error429'
      tags:
      - Integrations
      x-infranest-scope: cloud.read
      x-infranest-token-writable: false
      x-infranest-module: integrations
      x-infranest-errors:
      - unauthenticated
      - scope_missing
      - wrong_organization
      - test_token_required
      - test_token_sandbox_only
      - permission_denied
      - not_found
      - rate_limited
  /api/organizations/{organization_id}/integrations/{provider}/activity:
    get:
      summary: List integration activity
      operationId: providerAPIActivity256TheIntegrationLogAcrossAllOfThisOrgsCredentialsForTheProviderPaginated+FilterableaccountCapabilityStatusSearchFollowingTheStandardServerTableContractSoTheDetailPagesActivityTabUsesTheSharedDataTable
      description: The calls made to and received from this integration, newest first, paginated with `per_page` (5 to 100, default 20). Filter with `status` (`success` or `error`), `capability`, `direction`, `credential_id` and `search`; `meta` lists the accounts and filter values available.
      parameters:
      - in: path
        name: organization_id
        required: true
        description: Your organization's ID.
        schema:
          type: integer
      - in: path
        name: provider
        required: true
        description: The provider.
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              example:
                data:
                - id: 9
                  credential_id: 1
                  capability: cloud
                  direction: outbound
                  method: GET
                  endpoint: /v1/servers
                  action: listServers
                  success: true
                  http_status: 200
                  duration_ms: 60
                  error_type: null
                  error_message: null
                  created_at: '2026-01-15T12:00:00.000000Z'
                - id: 10
                  credential_id: 1
                  capability: cloud
                  direction: outbound
                  method: GET
                  endpoint: /v1/volumes
                  action: listVolumes
                  success: true
                  http_status: 200
                  duration_ms: 112
                  error_type: null
                  error_message: null
                  created_at: '2026-01-15T11:57:00.000000Z'
                total: 672
                last_page: 34
                meta:
                  accounts:
                  - id: 1
                    label: Hetzner — Production
                    context: []
                  capabilities:
                  - cloud
                  directions:
                  - outbound
                  rate_limit: null
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '429':
          $ref: '#/components/responses/Error429'
      tags:
      - Integrations
      x-infranest-scope: cloud.read
      x-infranest-token-writable: false
      x-infranest-module: integrations
      x-infranest-errors:
      - unauthenticated
      - scope_missing
      - wrong_organization
      - test_token_required
      - test_token_sandbox_only
      - permission_denied
      - not_found
      - rate_limited
  /api/organizations/{organization_id}/integrations/{provider}/accounts/{id}:
    get:
      summary: Get an integration account
      operationId: gETOrganizationsorganizationintegrationsprovideraccountsid
      description: One connected account of an integration, whatever kind it is, with its status and health. A provider account also carries `provider_status`, the same as in the list of integrations. Returns 404 when the account does not exist or does not belong to this integration and organization.
      parameters:
      - in: path
        name: organization_id
        required: true
        description: Your organization's ID.
        schema:
          type: integer
      - in: path
        name: provider
        required: true
        description: The provider.
        schema:
          type: string
      - in: path
        name: id
        required: true
        description: The id's ID.
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              example:
                id: 1
                provider: hetzner
                label: Hetzner — Production
                enabled: true
                removing: false
                is_oauth: false
                auth_kind: api_token
                oauth: null
                error_email_enabled: true
                sync_slowed: false
                alerts_muted_until: null
                incident: null
                notices: []
                spending: null
                capabilities:
                - cloud
                - dns
                supported_capabilities:
                - cloud
                - dns
                cloud_capabilities:
                  native_delete_protection: true
                  server_destroy: true
                  server_destroy_is_cancellation: false
                  server_create: true
                  server_rename: true
                  server_resize: true
                  console: true
                  snapshots: true
                  backups: true
                  isos: true
                  rescue: true
                  placement_groups: true
                  public_network_toggle: true
                  scheduled_backups: true
                  private_networks: true
                  private_network_attach: true
                  network_join_on_create: false
                  network_attach_ip_choice: true
                  private_network_unfiltered: true
                  floating_ips: true
                  networks_creatable: true
                  network_cidr: true
                  network_subnets: true
                  network_routes: true
                  network_rename: true
                  network_ip_range_extendable: true
                  firewalls_creatable: true
                  firewall_multi_server: true
                  firewall_renamable: true
                  firewall_outbound: true
                  firewall_ipv6: true
                  firewall_dynamic_ip: true
                  server_firewall: false
                  load_balancers_creatable: true
                  load_balancer_rename: true
                  load_balancer_algorithm: true
                  load_balancer_services: true
                  load_balancer_targets: true
                  volumes_creatable: true
                  volume_resize: true
                  volume_rename: true
                  volume_native_delete_protection: true
                  volume_snapshots: false
                  network_native_delete_protection: true
                  user_data: true
                  install_flavour: false
                  images_per_plan: false
                  metrics: true
                  metrics_disk_throughput: true
                  metrics_memory_disk: false
                  rdns_subnet: true
                  rdns_address_list: false
                  reverse_dns: true
                  snapshot_description: true
                  snapshot_protection: true
                dns_capabilities:
                  record_writes: true
                  bulk_replace: false
                  zone_create: true
                  zone_delete: true
                  record_proxying: false
                  signing: false
                dns_scope: any
                cloud_firewall_protocols:
                - tcp
                - udp
                enabled_capabilities: null
                suspended_capabilities: []
                resource_counts:
                  dns: 2
                  certificates: 1
                  cloud: 6
                verified_at: '2025-10-15T12:00:00.000000Z'
                created_at: '2026-01-15T12:00:00.000000Z'
                fields:
                - api_token
                environment: null
                field_values:
                  api_token:
                    set: true
                    secret: true
                    display: ••••oken
                context: []
                health:
                  status: ok
                  success_rate: 100
                  total_calls: 97
                  last_error_at: null
                  last_success_at: '2026-01-15T12:00:00Z'
                registrar_operations: null
                provider_status: null
                scope_check: null
                scope_checked_at: null
                disabled_operations: []
                api_base: /organizations/1/provider-credentials/1
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '429':
          $ref: '#/components/responses/Error429'
      tags:
      - Integrations
      x-infranest-scope: cloud.read
      x-infranest-token-writable: false
      x-infranest-module: integrations
      x-infranest-errors:
      - unauthenticated
      - scope_missing
      - wrong_organization
      - test_token_required
      - test_token_sandbox_only
      - permission_denied
      - not_found
      - rate_limited
  /api/organizations/{organization_id}/integrations/{provider}:
    get:
      summary: Get an integration
      operationId: appStoreDetailForOneProvider256TheCodeOwnedStructuralConfig+DirectusPresentationContentresolvedForTheRequestLocale+ThisOrgsExistingConnectionsForThatProvider
      description: What the integration offers, the organization’s connections to it, and whether your plan allows connecting it. Returns 404 for an unknown integration.
      parameters:
      - in: path
        name: organization_id
        required: true
        description: Your organization's ID.
        schema:
          type: integer
      - in: path
        name: provider
        required: true
        description: The provider.
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              example:
                provider:
                  key: hetzner
                  label: Hetzner
                  logo: hetzner
                  capabilities:
                  - cloud
                  - dns
                  categories:
                  - cloud
                  - dns
                  dns_scope: any
                  features:
                  - zone_discovery
                  - record_ids
                  environments: []
                  oauth: false
                  one_click: false
                  needs_allowlist: false
                  featured: true
                  premium: false
                  min_plan: null
                  max_connections: null
                  credentials:
                  - key: api_token
                    label: integrations.providers.hetzner.apiToken.label
                    secret: true
                    multiline: false
                    help: integrations.providers.hetzner.apiToken.help
                    help_params:
                      aws_account_id: InfraNest's AWS account (set AWS_INFRANEST_ACCOUNT_ID)
                    placeholder: LRK9mXv2QpT8sYw4…
                    prefill: null
                    type: text
                    options: null
                    depends_on: null
                    show_when: null
                    default: null
                  kind: provider
                  content: null
                connections:
                - id: 1
                  kind: provider
                  provider: hetzner
                  integration_key: hetzner
                  name: Hetzner — Production
                  categories:
                  - cloud
                  - dns
                  capabilities:
                  - cloud
                  - dns
                  counts:
                    servers: 6
                    zones: 2
                    domains: 0
                    certs: 1
                  suspended_capabilities: []
                  incident: null
                  auth_kind: api_token
                  enabled: true
                  status: connected
                  locked: false
                  health:
                    status: ok
                    success_rate: 100
                    total_calls: 97
                    last_error_at: null
                    last_success_at: '2026-01-15T12:00:00Z'
                  rate_limited: null
                  last_activity_at: '2026-01-15T12:00:00Z'
                  provider_status: null
                gate:
                  locked: false
                  reason: null
                  premium: false
                  min_plan: null
                  min_plan_name: null
                  current_plan: pro
                  current_plan_name: Pro
                  max_connections: null
                  used: 1
                  grandfathered: false
                  included: false
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '429':
          $ref: '#/components/responses/Error429'
      tags:
      - Integrations
      x-infranest-scope: cloud.read
      x-infranest-token-writable: false
      x-infranest-module: integrations
      x-infranest-errors:
      - unauthenticated
      - scope_missing
      - wrong_organization
      - test_token_required
      - test_token_sandbox_only
      - permission_denied
      - not_found
      - rate_limited
  /api/organizations/{organization_id}/connect-requests:
    get:
      summary: List connect requests
      operationId: gETOrganizationsorganizationconnectRequestsprovider
      description: The 20 most recent links you created to ask someone else to connect a provider account, newest first, with who requested each one. Filter with `provider` or `kind`; the response also gives how many days a new link stays valid.
      parameters:
      - in: path
        name: organization_id
        required: true
        description: Your organization's ID.
        schema:
          type: integer
      responses:
        '200':
          description: OK
          content:
            application/json:
              example:
                data: []
                ttl_days: 3
        '401':
          $ref: '#/components/responses/Error401'
        '403':
          $ref: '#/components/responses/Error403'
        '404':
          $ref: '#/components/responses/Error404'
        '429':
          $ref: '#/components/responses/Error429'
      tags:
      - Integrations
      x-infranest-scope: cloud.read
      x-infranest-token-writable: false
      x-infranest-module: cloud
      x-infranest-errors:
      - unauthenticated
      - scope_missing
      - wrong_organization
      - test_token_required
      - test_token_sandbox_only
      - permission_denied
      - not_found
      - rate_limited
components:
  responses:
    Error401:
      description: The token is missing, wrong, expired or revoked. The body is an Error; its `code` says which.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error404:
      description: Nothing exists at this address, or you cannot see it. The body is an Error; its `code` says which.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error429:
      description: 'Too many requests: wait the seconds in Retry-After. The body is an Error; its `code` says which.'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Error403:
      description: The token or your role may not do this here. The body is an Error; its `code` says which.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      required:
      - code
      - message
      - hint
      - retryable
      properties:
        code:
          type: string
          enum:
          - unauthenticated
          - scope_missing
          - session_only
          - not_token_writable
          - write_disabled
          - wrong_organization
          - token_ip_not_allowed
          - test_token_required
          - test_token_sandbox_only
          - api_token_required
          - sandbox_personal
          - sandbox_needs_organization
          - organization_offline
          - permission_denied
          - forbidden
          - organization_suspended
          - read_only_session
          - sso_required
          - two_factor_setup_required
          - password_reset_required
          - email_verification_required
          - plan_limit
          - not_found
          - method_not_allowed
          - conflict
          - validation_failed
          - unprocessable
          - range_too_large
          - rate_limited
          - idempotency_key_reused
          - idempotency_in_progress
          - provider_refused
          - provider_rate_limited
          - provider_unavailable
          - maintenance
          - server_error
          description: 'What kind of error this is. Stable: codes are added, never renamed or removed.'
        message:
          type: string
          description: A sentence for people. May be reworded.
        hint:
          type: string
          description: What to do about it.
        retryable:
          type: boolean
          description: Whether the same request can succeed later unchanged.
        docs_url:
          type: string
          format: uri
        reference:
          type: string
          description: The request ID; also the X-Request-Id header.
        retry_after:
          type: integer
          description: Seconds to wait before retrying.
        required:
          type: string
          description: The missing token scope (scope_missing).
        required_permission:
          type: string
          description: The missing role permission (permission_denied).
        errors:
          type: object
          additionalProperties:
            type: array
            items:
              type: string
  securitySchemes:
    default:
      type: http
      scheme: bearer
      description: Create a token in the app under My account → Developer. Tokens are managed in the app only, never through the API.
externalDocs:
  description: 'InfraNest: domains, DNS, cloud servers, certificates and uptime monitoring in one place'
  url: https://infranest.io