Cavuno Integrations API

openapi: 3.2.0
info:
  title: Cavuno v1 REST Integrations API
  version: 1.0.0
  description: 'The Cavuno API is organized around REST. Our API has predictable resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs. ## Base URL


    Production: `https://api.cavuno.com/v1`


    All API requests must be made over HTTPS. Calls made over plain HTTP will fail. ## Authentication


    The Cavuno API uses API keys to authenticate requests. You can view and manage your API keys in the Cavuno dashboard, under Settings → Developer → API keys. Cavuno API keys have the prefix `cavuno_live_`. Your API keys carry many privileges, so be sure to keep them secure. Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth. Authentication to the API is performed via Bearer auth. Provide your API key as the bearer token in the `Authorization` header:


    ```bash

    curl https://api.cavuno.com/v1/jobs \

    -H "Authorization: Bearer YOUR_SECRET_API_KEY"

    ```


    API requests without authentication will fail. ## Rate limits


    The Cavuno API has rate limits in place to ensure stability and reliability. By default, API keys are limited to 100 requests per minute. If you exceed your limit, requests return an HTTP 429 response with a `Retry-After` header indicating when you can try again. If you have a use case that needs a higher limit, contact support. ## Idempotency


    The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. For example, if a request to create a job fails due to a network connection error, you can safely retry the request with the same idempotency key, and we''ll guarantee that only one job is created. To perform an idempotent request, provide an additional `Idempotency-Key` header on any `POST`, `PATCH`, or `DELETE` request:


    ```bash

    curl https://api.cavuno.com/v1/jobs \

    -X POST \

    -H "Authorization: Bearer cavuno_live_..." \

    -H "Idempotency-Key: $(uuidgen)" \

    -H "Content-Type: application/json" \

    -d ''{ "title": "Senior Engineer" }''

    ```


    ## Errors


    Cavuno uses conventional HTTP response codes to indicate the success or failure of an API request. In general: codes in the `2xx` range indicate success, codes in the `4xx` range indicate an error that failed given the information provided (e.g., a required parameter was omitted), and codes in the `5xx` range indicate an error with Cavuno''s servers (these are rare). Error responses include a JSON body with details:


    ```json

    {

    "error": {

    "code": "validation_bad_request",

    "message": "Field ''title'' is required.",

    "requestId": "req_..."

    }

    }

    ```


    Some errors carry an additional `details` field with structured context, such as per-field validation issues. ### Plan upgrade hints


    When an Operator API request is refused because of the board''s Cavuno plan, the error also carries an `upgrade` object. It names the capability that blocked the request, the cheapest self-serve plan that unlocks it (when that can be told), and the hosted billing endpoints that start the upgrade:


    ```json

    {

    "error": {

    "code": "settings_plan_required_for_branding_removal",

    "message": "Removing Cavuno branding requires a plan that includes branding removal.",

    "requestId": "req_...",

    "upgrade": {

    "capability": "canRemoveBranding",

    "requiredPlan": "basic",

    "checkout": { "method": "POST", "path": "/v1/billing/checkout" },

    "changePlan": { "method": "POST", "path": "/v1/billing/upgrade" }

    }

    }

    }

    ```


    Call `GET /v1/billing/subscription` first. With no active subscription, use `checkout`; with one, use `changePlan`. Send `{ "planKey": "" }` and give the returned `url` to a person: both endpoints return a hosted page where a person confirms the purchase. Nothing is charged until they do. Each `path` is relative to the API origin (`https://api.cavuno.com`), like `Location` headers and list `url` fields, so do not join it to a base URL that already ends in `/v1`.'
  contact:
    name: Cavuno
    url: https://cavuno.com
servers:
- url: https://api.cavuno.com/v1
  description: Production
security:
- bearerAuth: []
tags:
- name: Integrations
  description: Search-indexing and analytics-reporting integrations.
paths:
  /integrations/indexing:
    get:
      summary: Retrieve the indexing configuration
      description: Returns the account's Google Indexing API and IndexNow configuration. The Google Indexing API notifies Google immediately when jobs are published or removed; your site is indexed by Google either way. Always returns a config (the Google Indexing API reads as disabled when never provisioned). Toggle it with `POST /v1/integrations/indexing/toggle-google-indexing-api`.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IndexingConfig'
        default:
          description: An error. Every non-2xx response uses the same envelope; see the Errors section of the introduction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-audience: operator
      tags:
      - Integrations
      operationId: getIntegrationsIndexing
  /integrations/indexing/submissions:
    get:
      summary: List indexing submissions
      description: 'Lists the Board''s search-indexing submissions, newest first: each page URL sent to the Google Indexing API when a job, company or blog post is published or removed, with its state, retries and last error. Filter by `state` or by a page `url` to see why one page was not submitted.'
      parameters:
      - schema:
          type: string
          minLength: 1
        required: false
        name: cursor
        in: query
      - schema:
          type: integer
          minimum: 1
          maximum: 100
        required: false
        name: limit
        in: query
      - schema:
          type: string
          enum:
          - pending
          - submitted
          - error
          - failed
          - skipped
          description: Only return submissions in this state.
        required: false
        description: Only return submissions in this state.
        name: state
        in: query
      - schema:
          type: string
          minLength: 1
          description: Only return submissions for this page path, for example `/companies/acme/jobs/engineer`. A full URL also works and is reduced to its path. Combined with `state`, pages can hold fewer rows than `limit` while `hasMore` is true.
        required: false
        description: Only return submissions for this page path, for example `/companies/acme/jobs/engineer`. A full URL also works and is reduced to its path. Combined with `state`, pages can hold fewer rows than `limit` while `hasMore` is true.
        name: url
        in: query
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    enum:
                    - list
                  url:
                    type: string
                    example: /v1/integrations/indexing/submissions
                  hasMore:
                    type: boolean
                  nextCursor:
                    type:
                    - string
                    - 'null'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/IndexingSubmission'
                required:
                - object
                - url
                - hasMore
                - nextCursor
                - data
        '400':
          description: The pagination cursor or query is invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-audience: operator
      tags:
      - Integrations
      operationId: listIndexingSubmissions
  /integrations/indexing/toggle-google-indexing-api:
    post:
      summary: Toggle the Google Indexing API
      description: 'Enables or disables the Google Indexing API, which notifies Google immediately when jobs are published or removed. Your site is indexed by Google either way; this only speeds up how quickly Google learns about job changes. Enabling runs the same checks as Settings → Indexing in the dashboard, in this order: the board has a primary custom domain; the board is not password protected; the board''s Google Cloud project is provisioned (this starts automatically when a custom domain becomes primary); and the board''s service account is an Owner of the site in Google Search Console. When Search Console is connected, the service account is added as an Owner automatically. Disabling always succeeds.'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IndexingToggleBody'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IndexingConfig'
        '400':
          description: '`integrations_board_not_configured`: the account has no board.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: 'A prerequisite for enabling is not met. `integrations_indexing_custom_domain_required`: connect a custom domain and set it as primary. `integrations_indexing_password_protected`: remove board password protection. `integrations_indexing_setup_not_ready`: the Google Cloud project is not provisioned yet, or its service account credentials are unusable; `details.provisioningStatus` is the current state (`pending`, `provisioning`, `ready`, `error`, or `null` when setup never started). Start or retry setup from Settings → Indexing. `integrations_indexing_search_console_access_required`: add the service account in `details.serviceAccountEmail` as an Owner of the site in Google Search Console, then retry.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: '`integrations_indexing_verification_failed`: Google did not confirm Search Console access (an unexpected Google response, or Google was unreachable). `details.serviceAccountEmail` is the service account that must be an Owner. Retry later.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-audience: operator
      tags:
      - Integrations
      operationId: toggleGoogleIndexingApi
  /integrations/indexing/toggle-indexnow:
    post:
      summary: Toggle IndexNow
      description: Enables or disables IndexNow (Bing/Yandex instant indexing). Enabling is refused (409) while board password protection is active.
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/IndexingToggleBody'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/IndexingConfig'
        default:
          description: An error. Every non-2xx response uses the same envelope; see the Errors section of the introduction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-audience: operator
      tags:
      - Integrations
      operationId: toggleIndexNow
  /integrations/reporting:
    get:
      summary: List reporting integrations
      description: Returns normalized connection state for the Board's reporting integrations. Provider identifiers, grants, credentials, settings, and collector telemetry are not returned.
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    enum:
                    - list
                  url:
                    type: string
                    example: /v1/integrations/reporting
                  hasMore:
                    type: boolean
                  nextCursor:
                    type:
                    - string
                    - 'null'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/ReportingIntegration'
                required:
                - object
                - url
                - hasMore
                - nextCursor
                - data
        default:
          description: An error. Every non-2xx response uses the same envelope; see the Errors section of the introduction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-audience: operator
      tags:
      - Integrations
      operationId: listIntegrationsReporting
  /integrations/reporting/{provider}:
    get:
      summary: Retrieve a reporting integration
      description: Returns a single reporting integration by provider key, or 404 if the account has none for that provider.
      parameters:
      - schema:
          type: string
          enum:
          - search_console
          - adsense
          - tinybird
          - stripe
          - google_analytics
          description: 'The reporting provider key. `tinybird` is deprecated: first-party Board analytics need no connection and are served live by the `/v1/analytics` endpoints, so connecting it changes nothing.'
        required: true
        description: 'The reporting provider key. `tinybird` is deprecated: first-party Board analytics need no connection and are served live by the `/v1/analytics` endpoints, so connecting it changes nothing.'
        name: provider
        in: path
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportingIntegration'
        default:
          description: An error. Every non-2xx response uses the same envelope; see the Errors section of the introduction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-audience: operator
      tags:
      - Integrations
      operationId: getIntegrationsReporting
    patch:
      summary: Enable or disable a reporting integration
      description: Pauses or resumes collection for an existing integration without disconnecting it. For Search Console, an account administrator with integration-management permission can also explicitly keep reads restricted to stored Board hostnames or authorize the entire selected Google property.
      parameters:
      - schema:
          type: string
          enum:
          - search_console
          - adsense
          - tinybird
          - stripe
          - google_analytics
          description: 'The reporting provider key. `tinybird` is deprecated: first-party Board analytics need no connection and are served live by the `/v1/analytics` endpoints, so connecting it changes nothing.'
        required: true
        description: 'The reporting provider key. `tinybird` is deprecated: first-party Board analytics need no connection and are served live by the `/v1/analytics` endpoints, so connecting it changes nothing.'
        name: provider
        in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchReportingIntegrationBody'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportingIntegration'
        default:
          description: An error. Every non-2xx response uses the same envelope; see the Errors section of the introduction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-audience: operator
      tags:
      - Integrations
      operationId: updateIntegrationsReporting
    delete:
      summary: Disconnect a reporting integration
      description: Deletes the integration. Stripe is managed from Monetization settings and cannot be disconnected here (409).
      parameters:
      - schema:
          type: string
          enum:
          - search_console
          - adsense
          - tinybird
          - stripe
          - google_analytics
          description: 'The reporting provider key. `tinybird` is deprecated: first-party Board analytics need no connection and are served live by the `/v1/analytics` endpoints, so connecting it changes nothing.'
        required: true
        description: 'The reporting provider key. `tinybird` is deprecated: first-party Board analytics need no connection and are served live by the `/v1/analytics` endpoints, so connecting it changes nothing.'
        name: provider
        in: path
      responses:
        '204':
          description: The integration was disconnected.
        default:
          description: An error. Every non-2xx response uses the same envelope; see the Errors section of the introduction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-audience: operator
      tags:
      - Integrations
      operationId: deleteIntegrationsReporting
  /integrations/reporting/{provider}/connect:
    post:
      summary: Connect a reporting integration
      description: Starts the connection flow. Some providers return a hosted authorization URL, some connect immediately, and payment reporting returns the Board payments-settings URL. Provider credentials and configuration are never returned.
      parameters:
      - schema:
          type: string
          enum:
          - search_console
          - adsense
          - tinybird
          - stripe
          - google_analytics
          description: 'The reporting provider key. `tinybird` is deprecated: first-party Board analytics need no connection and are served live by the `/v1/analytics` endpoints, so connecting it changes nothing.'
        required: true
        description: 'The reporting provider key. `tinybird` is deprecated: first-party Board analytics need no connection and are served live by the `/v1/analytics` endpoints, so connecting it changes nothing.'
        name: provider
        in: path
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ReportingConnect'
        default:
          description: An error. Every non-2xx response uses the same envelope; see the Errors section of the introduction.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-audience: operator
      tags:
      - Integrations
      operationId: connectIntegrationsReporting
components:
  schemas:
    ReportingIntegration:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the integration.
        object:
          type: string
          enum:
          - reporting_integration
          description: String representing the object's type.
        provider:
          type: string
          enum:
          - search_console
          - adsense
          - tinybird
          - stripe
          - google_analytics
          description: 'The reporting provider key. `tinybird` is deprecated: first-party Board analytics need no connection and are served live by the `/v1/analytics` endpoints, so connecting it changes nothing.'
        enabled:
          type: boolean
          description: Whether collection is enabled for this integration.
        connected:
          type: boolean
          description: Whether the connection has completed successfully.
        connectedAt:
          type:
          - string
          - 'null'
          description: ISO-8601 timestamp of when the integration was connected.
      required:
      - id
      - object
      - provider
      - enabled
      - connected
      - connectedAt
    IndexingConfig:
      type: object
      properties:
        id:
          type: string
          enum:
          - indexing_config
        object:
          type: string
          enum:
          - indexing_config
        enabled:
          type: boolean
          description: 'Whether the Google Indexing API is enabled: Google is notified immediately when jobs are published or removed. Your site is indexed by Google either way. `true` means setup is complete: Cavuno only enables it after Google confirms the service account is an Owner of the Search Console property, so there is nothing left to add or verify. Use `lastRunAt` and `lastError` to check that submissions keep succeeding.'
        indexNowEnabled:
          type: boolean
          description: Whether IndexNow (Bing/Yandex) instant indexing is enabled.
        provisioningStatus:
          type:
          - string
          - 'null'
          description: Provisioning state of the board's Google Cloud project for the Google Indexing API (`pending` | `provisioning` | `ready` | `error`), or null when setup has not started.
        lastRunAt:
          type:
          - string
          - 'null'
          description: ISO-8601 timestamp of the last successful Google Indexing API submission, or null. Submissions are sent when jobs are published or removed, so it stays null until the first one succeeds after indexing is enabled.
        lastError:
          type:
          - string
          - 'null'
          description: The last recorded Google Indexing API error message, or null.
        dailyQuota:
          type:
          - integer
          - 'null'
          description: Google Indexing API submissions allowed per day, or null when setup has not started.
        quotaUsedToday:
          type:
          - integer
          - 'null'
          description: Google Indexing API submissions used since the last quota reset, or null when setup has not started. Jobs published after the quota runs out wait for the reset.
        quotaResetAt:
          type:
          - string
          - 'null'
          description: ISO-8601 time the daily quota was last reset, or null.
        serviceAccountEmail:
          type:
          - string
          - 'null'
          description: The Board's Google service account email, or null before provisioning finishes. It must be added as an Owner of the Search Console property before the Google Indexing API can be enabled.
        searchConsoleVerified:
          type: boolean
          description: Whether Google confirmed that the service account is an Owner of the Search Console property.
      required:
      - id
      - object
      - enabled
      - indexNowEnabled
      - provisioningStatus
      - lastRunAt
      - lastError
      - dailyQuota
      - quotaUsedToday
      - quotaResetAt
      - serviceAccountEmail
      - searchConsoleVerified
    PatchReportingIntegrationBody:
      type: object
      properties:
        enabled:
          type: boolean
          description: Whether collection is enabled for this integration.
        searchConsoleCoverageMode:
          type: string
          enum:
          - board_hosts
          - whole_property
          description: Search Console only. board_hosts restricts reads to stored Board hostnames; whole_property explicitly authorizes the entire selected Google property.
      additionalProperties: false
    IndexingSubmission:
      type: object
      properties:
        id:
          type: string
        object:
          type: string
          enum:
          - indexing_submission
        url:
          type: string
          description: The page path as submitted, relative to the Board's domain, for example `/companies/acme/jobs/engineer`.
        entityType:
          type: string
          description: 'What the page shows: `job`, `company` or `blog`.'
        action:
          type: string
          description: '`url_updated`: the page was published or changed. `url_deleted`: the page was removed.'
        state:
          type: string
          description: '`pending`: waiting to be sent. `submitted`: Google accepted it. `error`: the last attempt failed and will be retried. `failed`: retries ran out. `skipped`: not sent, for example because indexing is off.'
        retryCount:
          type: integer
          minimum: 0
          description: Failed attempts so far.
        indexNowSubmitted:
          type: boolean
          description: Whether the URL was also sent to IndexNow (Bing, Yandex).
        error:
          type:
          - string
          - 'null'
          description: Error message of the last failed attempt, or null.
        createdAt:
          type: string
          description: ISO-8601 time the submission was queued.
        submittedAt:
          type:
          - string
          - 'null'
          description: ISO-8601 time Google accepted it, or null.
        nextAttemptAt:
          type:
          - string
          - 'null'
          description: ISO-8601 time of the next retry, or null when it is due now or will not be retried.
      required:
      - id
      - object
      - url
      - entityType
      - action
      - state
      - retryCount
      - indexNowSubmitted
      - error
      - createdAt
      - submittedAt
      - nextAttemptAt
    IndexingToggleBody:
      type: object
      properties:
        enabled:
          type: boolean
          description: Whether to enable the toggle.
      required:
      - enabled
    PlanUpgradeHint:
      type: object
      properties:
        capability:
          type: string
          enum:
          - activeJobsLimit
          - teamSeatLimit
          - canBePublic
          - canRemoveBranding
          - apiAccess
          description: The plan capability that blocked the request, named as in `GET /v1/billing/subscription` `capabilities`.
        requiredPlan:
          type: string
          enum:
          - starter
          - basic
          - grow
          - advanced
          - scale
          description: The cheapest self-serve plan that unlocks the action. Pass it as `planKey`. Omitted when it cannot be told without more information; read `GET /v1/billing/subscription` and pick a higher plan.
        checkout:
          type: object
          properties:
            method:
              type: string
              enum:
              - POST
            path:
              type: string
              enum:
              - /v1/billing/checkout
          required:
          - method
          - path
          description: Starts a hosted checkout when the board has no active subscription (for example during a trial).
        changePlan:
          type: object
          properties:
            method:
              type: string
              enum:
              - POST
            path:
              type: string
              enum:
              - /v1/billing/upgrade
          required:
          - method
          - path
          description: Starts a hosted plan change when the board already has an active subscription.
      required:
      - capability
      - checkout
      - changePlan
      description: 'Present only on Operator API errors caused by the board''s Cavuno plan. Read `GET /v1/billing/subscription` to choose between `checkout` and `changePlan`, call it with `{ "planKey": requiredPlan }`, and give the returned `url` to a person to confirm. Each `path` is relative to the API origin, not to a `/v1` base URL. Both endpoints need `billing.manage`. Board API errors never include it.'
    ReportingConnect:
      type: object
      properties:
        object:
          type: string
          enum:
          - reporting_integration_connect
          description: String representing the object's type.
        provider:
          type: string
          description: The reporting provider key.
        connected:
          type: boolean
          description: Whether the integration is already fully connected.
        authorizationUrl:
          type: string
          description: OAuth providers only. The URL the user must visit to grant access.
        siteUrl:
          type: string
          description: The board site URL the integration reports on.
        redirectUrl:
          type: string
          description: 'Stripe only: the Monetization settings deep link.'
      required:
      - object
      - provider
      - connected
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: Machine-readable error code, such as `validation_bad_request` or `jobs_not_found`.
            message:
              type: string
              description: Human-readable explanation.
            requestId:
              type: string
              description: Unique id for this request. Include it when contacting support.
            details:
              description: Structured context for some errors, such as per-field validation issues.
            upgrade:
              $ref: '#/components/schemas/PlanUpgradeHint'
          required:
          - code
          - message
          - requestId
      required:
      - error
      description: The error envelope returned by every non-2xx response.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: cavuno_live_<keyId>_<secret>
      description: Use your secret API key to authenticate. Pass it as a Bearer token in the `Authorization` header. You can view and manage your API keys in the Cavuno dashboard.
externalDocs:
  description: Cavuno API reference
  url: https://cavuno.com/docs/api