Cavuno Redirects API

openapi: 3.2.0
info:
  title: Cavuno v1 REST Redirects 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: Redirects
  description: Create, list, update, and delete board redirect rules.
paths:
  /redirects:
    get:
      summary: List redirect rules
      description: Returns redirect rules for the authenticated account, sorted by source path. Supports cursor pagination and optional prefix search on `fromPath`.
      parameters:
      - schema:
          type: string
          minLength: 1
          description: An opaque pagination cursor returned in the `nextCursor` field of a previous response.
        required: false
        description: An opaque pagination cursor returned in the `nextCursor` field of a previous response.
        name: cursor
        in: query
      - schema:
          type: integer
          minimum: 1
          maximum: 100
          description: A limit on the number of objects to be returned. Limit can range between 1 and 100.
        required: false
        description: A limit on the number of objects to be returned. Limit can range between 1 and 100.
        example: 50
        name: limit
        in: query
      - schema:
          type: string
          minLength: 1
          description: Prefix match against `fromPath`. Only redirects whose source path starts with this value are returned.
        required: false
        description: Prefix match against `fromPath`. Only redirects whose source path starts with this value are returned.
        name: search
        in: query
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    enum:
                    - list
                  url:
                    type: string
                    example: /v1/redirects
                  hasMore:
                    type: boolean
                  nextCursor:
                    type:
                    - string
                    - 'null'
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/Redirect'
                required:
                - object
                - url
                - hasMore
                - nextCursor
                - data
        '400':
          description: The request was malformed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-audience: operator
      tags:
      - Redirects
      operationId: listRedirects
    post:
      summary: Create a redirect rule
      description: Creates a redirect. The request is idempotent when an `Idempotency-Key` header is supplied.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateRedirectBody'
      responses:
        '201':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Redirect'
        '400':
          description: The request was malformed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: A redirect from this path already exists.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-audience: operator
      tags:
      - Redirects
      operationId: createRedirect
  /redirects/{id}:
    get:
      summary: Retrieve a redirect rule
      description: Retrieves a redirect rule by ID. Use it to read back a redirect you created or updated.
      parameters:
      - schema:
          type: string
          minLength: 1
          description: The redirect ID returned by create or list endpoints.
        required: true
        description: The redirect ID returned by create or list endpoints.
        name: id
        in: path
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Redirect'
        '404':
          description: Redirect not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-audience: operator
      tags:
      - Redirects
      operationId: getRedirect
    patch:
      summary: Update a redirect rule
      description: Updates the specified redirect by setting the values of the parameters passed. Any parameters not provided will be left unchanged.
      parameters:
      - schema:
          type: string
          minLength: 1
          description: The redirect ID returned by create or list endpoints.
        required: true
        description: The redirect ID returned by create or list endpoints.
        name: id
        in: path
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateRedirectBody'
      responses:
        '200':
          description: Successful response.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Redirect'
        '400':
          description: The request was malformed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Redirect not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: The new fromPath collides with another redirect.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-audience: operator
      tags:
      - Redirects
      operationId: updateRedirect
    delete:
      summary: Delete a redirect rule
      description: Permanently deletes a redirect rule. It cannot be undone.
      parameters:
      - schema:
          type: string
          minLength: 1
          description: The redirect ID returned by create or list endpoints.
        required: true
        description: The redirect ID returned by create or list endpoints.
        name: id
        in: path
      responses:
        '204':
          description: Successful response.
        '404':
          description: Redirect not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-audience: operator
      tags:
      - Redirects
      operationId: deleteRedirect
  /redirects/batch:
    post:
      summary: Run a batch of redirect operations
      description: Runs up to 100 redirect operations in a single request, with a 5 MB request body limit. Each sub-operation runs independently. Idempotency keys are honored on the batch itself, not on individual sub-operations.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RedirectsBatchRequest'
      responses:
        '200':
          description: Successful response. Inspect each entry of the `data` array for the per-sub-operation status.
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    enum:
                    - batch_result
                  data:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        status:
                          type: number
                        data: {}
                        error:
                          type: object
                          properties:
                            code:
                              type: string
                            message:
                              type: string
                            details: {}
                          required:
                          - code
                          - message
                      required:
                      - id
                      - status
                required:
                - object
                - data
        '413':
          description: The request body exceeded 5 MB.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-audience: operator
      tags:
      - Redirects
      operationId: batchRedirects
components:
  schemas:
    UpdateRedirectBody:
      type: object
      properties:
        fromPath:
          type: string
          minLength: 1
          description: Source path to match, for example `/old-careers`.
        toPath:
          type: string
          minLength: 1
          description: Destination path or URL, for example `/jobs`.
        statusCode:
          anyOf:
          - type: number
            enum:
            - 301
          - type: number
            enum:
            - 302
          description: HTTP status code. One of `301` or `302`.
      additionalProperties: false
    CreateRedirectBody:
      type: object
      properties:
        fromPath:
          type: string
          minLength: 1
          description: Source path to match, for example `/old-careers`.
        toPath:
          type: string
          minLength: 1
          description: Destination path or URL, for example `/jobs`.
        statusCode:
          anyOf:
          - type: number
            enum:
            - 301
          - type: number
            enum:
            - 302
          default: 301
          description: HTTP status code. One of `301` or `302`. Defaults to `301`.
      required:
      - fromPath
      - toPath
      additionalProperties: false
    Redirect:
      type: object
      properties:
        id:
          type: string
          description: Unique identifier for the redirect.
        object:
          type: string
          enum:
          - redirect
          description: String representing the object's type. Objects of the same type share the same value.
        fromPath:
          type: string
          description: Source path matched by this redirect.
        toPath:
          type: string
          description: Destination path or URL.
        statusCode:
          anyOf:
          - type: number
            enum:
            - 301
          - type: number
            enum:
            - 302
          description: HTTP status code used when redirecting.
        createdAt:
          type: string
          description: Time at which the redirect was created. ISO 8601 datetime.
      required:
      - id
      - object
      - fromPath
      - toPath
      - statusCode
      - createdAt
    RedirectsBatchRequest:
      type: object
      properties:
        operations:
          type: array
          items:
            oneOf:
            - type: object
              properties:
                id:
                  type: string
                  minLength: 1
                method:
                  type: string
                  enum:
                  - POST
                body: {}
                action:
                  type: string
                resourceId:
                  type: string
              required:
              - id
              - method
            - type: object
              properties:
                id:
                  type: string
                  minLength: 1
                method:
                  type: string
                  enum:
                  - PATCH
                body: {}
                resourceId:
                  type: string
                  minLength: 1
              required:
              - id
              - method
              - resourceId
            - type: object
              properties:
                id:
                  type: string
                  minLength: 1
                method:
                  type: string
                  enum:
                  - DELETE
                resourceId:
                  type: string
                  minLength: 1
              required:
              - id
              - method
              - resourceId
          minItems: 1
          maxItems: 100
          description: Array of sub-operations to execute. Each entry runs independently and reports its result on the corresponding entry of the response `data` array. Sub-operation `id` values must be unique within the batch. Up to 100 entries.
      required:
      - operations
      additionalProperties: false
    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