Cavuno Sales-led plans API

openapi: 3.2.0
info:
  title: Cavuno v1 REST Sales-led plans 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: Sales-led plans
  description: 'Contact-led employer pricing cards: create, reorder, publish, hide, and archive.'
paths:
  /sales-led-plans:
    get:
      deprecated: true
      summary: List sales-led plans
      description: 'Deprecated. Use plans with `purpose: employer_service` and `pricingMode: contact`. List active (non-archived) contact-led pricing cards for the Board, ordered by `displayOrder`. Requires `plans.read`.'
      responses:
        '200':
          description: A list of sales-led plans.
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    enum:
                    - list
                  url:
                    type: string
                    example: /v1/sales-led-plans
                  hasMore:
                    type: boolean
                  nextCursor:
                    type:
                    - string
                    - 'null'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AdminSalesLedPlan'
                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:
      - Sales-led plans
      operationId: listSalesLedPlans
    post:
      deprecated: true
      summary: Create a sales-led plan
      description: Deprecated. Create an employer-service contact plan instead. This operation remains available for compatibility. Destination is normalized (email → mailto:, bare domain → https://). Max five featured bullets; max 50 active plans. Requires `plans.manage` and an `Idempotency-Key` header.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateSalesLedPlanBody'
      responses:
        '201':
          description: The created sales-led plan.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminSalesLedPlan'
        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:
      - Sales-led plans
      operationId: createSalesLedPlan
  /sales-led-plans/{id}:
    get:
      deprecated: true
      summary: Retrieve a sales-led plan
      description: Deprecated. Use the corresponding employer-service contact plan. Retrieve one active sales-led plan. Foreign and archived IDs return opaque 404. Requires `plans.read`.
      parameters:
      - schema:
          type: string
          minLength: 1
          description: The sales-led plan ID returned by create or list endpoints.
        required: true
        description: The sales-led plan ID returned by create or list endpoints.
        name: id
        in: path
      responses:
        '200':
          description: The sales-led plan.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminSalesLedPlan'
        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:
      - Sales-led plans
      operationId: getSalesLedPlan
    patch:
      deprecated: true
      summary: Update a sales-led plan
      description: Deprecated. Update the corresponding employer-service contact plan. This compatibility operation replaces the editable fields of an active sales-led plan. Requires `plans.manage` and an `Idempotency-Key` header.
      parameters:
      - schema:
          type: string
          minLength: 1
          description: The sales-led plan ID returned by create or list endpoints.
        required: true
        description: The sales-led plan ID returned by create or list endpoints.
        name: id
        in: path
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateSalesLedPlanBody'
      responses:
        '200':
          description: The updated sales-led plan.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminSalesLedPlan'
        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:
      - Sales-led plans
      operationId: updateSalesLedPlan
  /sales-led-plans/reorder:
    post:
      deprecated: true
      summary: Reorder sales-led plans
      description: Deprecated. Reorder employer-service contact plans instead. This compatibility operation atomically sets `displayOrder` for the complete active sales-led set. Rejects missing, foreign, archived, or duplicate IDs and duplicate orders. Requires `plans.manage` and an `Idempotency-Key` header.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ReorderSalesLedPlansBody'
      responses:
        '200':
          description: The reordered list of active sales-led plans.
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    enum:
                    - list
                  url:
                    type: string
                    example: /v1/sales-led-plans
                  hasMore:
                    type: boolean
                  nextCursor:
                    type:
                    - string
                    - 'null'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/AdminSalesLedPlan'
                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:
      - Sales-led plans
      operationId: reorderSalesLedPlans
  /sales-led-plans/{id}/publish:
    post:
      deprecated: true
      summary: Publish a sales-led plan
      description: 'Deprecated. Publish the corresponding employer-service contact plan. This compatibility operation sets `isPublic: true`. Requires `plans.manage` and an `Idempotency-Key` header.'
      parameters:
      - schema:
          type: string
          minLength: 1
          description: The sales-led plan ID returned by create or list endpoints.
        required: true
        description: The sales-led plan ID returned by create or list endpoints.
        name: id
        in: path
      responses:
        '200':
          description: The published sales-led plan.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminSalesLedPlan'
        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:
      - Sales-led plans
      operationId: publishSalesLedPlan
  /sales-led-plans/{id}/hide:
    post:
      deprecated: true
      summary: Hide a sales-led plan
      description: 'Deprecated. Hide the corresponding employer-service contact plan. This compatibility operation sets `isPublic: false` without archiving the sales-led row. Requires `plans.manage` and an `Idempotency-Key` header.'
      parameters:
      - schema:
          type: string
          minLength: 1
          description: The sales-led plan ID returned by create or list endpoints.
        required: true
        description: The sales-led plan ID returned by create or list endpoints.
        name: id
        in: path
      responses:
        '200':
          description: The hidden sales-led plan.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminSalesLedPlan'
        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:
      - Sales-led plans
      operationId: hideSalesLedPlan
  /sales-led-plans/{id}/archive:
    post:
      deprecated: true
      summary: Archive a sales-led plan
      description: 'Deprecated. Archive the corresponding employer-service contact plan. This compatibility operation soft-deletes the sales-led row by setting `isArchived: true` and `isPublic: false`. Archived IDs become opaque 404. Requires `plans.manage` and an `Idempotency-Key` header.'
      parameters:
      - schema:
          type: string
          minLength: 1
          description: The sales-led plan ID returned by create or list endpoints.
        required: true
        description: The sales-led plan ID returned by create or list endpoints.
        name: id
        in: path
      responses:
        '200':
          description: The archived sales-led plan.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AdminSalesLedPlan'
        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:
      - Sales-led plans
      operationId: archiveSalesLedPlan
components:
  schemas:
    AdminSalesLedPlan:
      type: object
      properties:
        id:
          type: string
          description: Cavuno salesLedEmployerPlans ID.
        object:
          type: string
          enum:
          - sales_led_plan
        name:
          type: string
        description:
          type: string
        priceText:
          type: string
        ctaText:
          type: string
        ctaDestination:
          type: string
        featuredBullets:
          type: array
          items:
            type: string
        isPublic:
          type: boolean
        displayOrder:
          type: integer
        createdAt:
          type: string
          description: ISO-8601 creation timestamp.
      required:
      - id
      - object
      - name
      - description
      - priceText
      - ctaText
      - ctaDestination
      - featuredBullets
      - isPublic
      - displayOrder
      - createdAt
      description: Deprecated. Prefer plans with purpose employer_service and pricingMode contact.
    ReorderSalesLedPlansBody:
      type: object
      properties:
        orders:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                minLength: 1
                description: Cavuno sales-led plan ID from list/create.
              displayOrder:
                type: integer
                minimum: 0
            required:
            - id
            - displayOrder
            additionalProperties: false
          description: 'Complete active set: every non-archived plan id exactly once, with unique displayOrder values.'
      required:
      - orders
      additionalProperties: false
    CreateSalesLedPlanBody:
      type: object
      properties:
        name:
          type: string
          minLength: 1
        description:
          type: string
          minLength: 1
        priceText:
          type: string
          minLength: 1
        ctaText:
          type: string
          minLength: 1
        ctaDestination:
          type: string
          minLength: 1
          description: Email address or URL. Bare emails become mailto:; bare domains become https://.
        featuredBullets:
          type: array
          items:
            type: string
          maxItems: 5
          description: Up to five feature bullets shown on the pricing card.
        isPublic:
          type: boolean
          description: Whether the plan is shown on the public employer pricing page.
        displayOrder:
          type: integer
          minimum: 0
          description: Sort order among active sales-led plans (lower first).
      required:
      - name
      - description
      - priceText
      - ctaText
      - ctaDestination
      - featuredBullets
      - isPublic
      - displayOrder
      additionalProperties: false
      description: Deprecated. Prefer creating a plan with purpose employer_service and pricingMode contact.
    UpdateSalesLedPlanBody:
      type: object
      properties:
        name:
          type: string
          minLength: 1
        description:
          type: string
          minLength: 1
        priceText:
          type: string
          minLength: 1
        ctaText:
          type: string
          minLength: 1
        ctaDestination:
          type: string
          minLength: 1
          description: Email address or URL. Bare emails become mailto:; bare domains become https://.
        featuredBullets:
          type: array
          items:
            type: string
          maxItems: 5
          description: Up to five feature bullets shown on the pricing card.
        isPublic:
          type: boolean
          description: Whether the plan is shown on the public employer pricing page.
        displayOrder:
          type: integer
          minimum: 0
          description: Sort order among active sales-led plans (lower first).
      required:
      - name
      - description
      - priceText
      - ctaText
      - ctaDestination
      - featuredBullets
      - isPublic
      - displayOrder
      additionalProperties: false
      description: Deprecated. Prefer updating the corresponding employer-service contact plan.
    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.'
    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