---
title: "Create a company"
method: POST
path: "/companies"
tags: ["Companies"]
---

# Create a company

`POST /companies`

## Request

- Base URL: `https://api.cavuno.com/v1`
- URL: `https://api.cavuno.com/v1/companies`
- Auth: HTTP bearer

Creates a new company. A logo is auto-fetched from `website` when available. The request is idempotent when an `Idempotency-Key` header is supplied.

## Request body

- CreateCompanyBody
  - `website` string, nullable: Public company website URL. Normalized to a canonical apex domain when stored. `null` or `""` means not set.
  - `summary` string, nullable: One-line summary of the company. Up to 280 characters. `null` or `""` means not set.
  - `description` string, nullable: Long-form description of the company, as HTML. Up to 25,000 characters. The HTML is sanitized on write: tags and attributes outside the supported formatting set (paragraphs, headings, lists, links, inline emphasis) are removed. Plain text without HTML tags is converted to paragraphs. `null` or `""` means not set.
  - `xUrl` string, nullable: X (Twitter) profile URL or handle. Stored as the canonical handle. `null` or `""` means not set.
  - `linkedinUrl` string, nullable: LinkedIn company page URL. `null` or `""` means not set.
  - `facebookUrl` string, nullable: Facebook company page URL. `null` or `""` means not set.
  - `instagramUrl` string, nullable: Instagram profile URL or handle. `null` or `""` means not set.
  - `markets` string[]: Canonical market slugs assigned to the company. Pass an empty array to clear all markets.
  - `name` string, required: The company's display name.
  - `slug` string: URL-friendly slug for the company. Auto-generated from `name` when omitted.

## Response `201`

Successful response.

- Company
  - `id` string, required: Unique identifier for the object. Use this value as the `{id}` path parameter for the company endpoints (e.g. `GET /v1/companies/{id}`).
  - `object` 'company', required: String representing the object's type. Objects of the same type share the same value.
  - `name` string, required: Display name of the company.
  - `slug` string, required: URL-friendly slug for the company.
  - `website` string, nullable, required: Public company website URL, or `null` if not set.
  - `logoUrl` string, nullable, required: URL of the company logo, or `null` if no logo is set.
  - `summary` string, nullable, required: One-line summary of the company, or `null` if not set.
  - `markets` string[], required: Canonical market slugs assigned to the company.
  - `xUrl` string, nullable, required: X (Twitter) profile URL, or `null` if not set.
  - `linkedinUrl` string, nullable, required: LinkedIn page URL, or `null` if not set.
  - `facebookUrl` string, nullable, required: Facebook page URL, or `null` if not set.
  - `instagramUrl` string, nullable, required: Instagram profile URL, or `null` if not set.
  - `createdAt` string, required: Time at which the company was created. ISO 8601 datetime.
  - `updatedAt` string, nullable, required: Time at which the company was last updated, or `null` if it has never been updated. ISO 8601 datetime.
  - `revision` integer, required: Public Company lifecycle revision. Historical rows may be 0 until rollout backfill.
  - `links` object, required: Public + admin URLs for this company. `public` may be `null` if the company lacks a slug.
    - `public` string, uri, nullable, required: Canonical public URL for this company on the board, or `null` when no slug is set.
    - `admin` string, uri, required: URL inside the Cavuno app where the authenticated owner can manage this resource.
  - `description` string, nullable, required: Long-form description of the company (HTML), or `null` if not set.
  - `canBackfill` boolean, nullable, required: Whether automated backfill of jobs from this company is supported, or `null` if not yet evaluated.
  - `jobCount` number, required: Total number of jobs at this company across all statuses.
  - `publishedJobCount` number, required: Number of currently-published jobs at this company.

## Other responses

- `400`: The request was malformed.
- `409`: Another company already uses the same website domain or name.

## Changes

- **2026-10-20** `d5974dabff14`: 2 warning, 9 info
  - the `name` request property's maxLength was set to `120`
  - the `website` request property's maxLength was set to `200`
  - added the new optional request property `description`
  - added the new optional request property `facebookUrl`
  - …7 more
- **2026-10-20** `cee1c2d567e5`: 1 breaking, 8 warning
  - the request property `website` became not nullable
  - removed the request property `description`
  - removed the request property `facebookUrl`
  - removed the request property `instagramUrl`
  - …5 more
- **2026-10-19** `c34152c38176`: 2 warning, 11 info
  - the `name` request property's maxLength was set to `120`
  - the `website` request property's maxLength was set to `200`
  - added the new optional request property `description`
  - added the new optional request property `facebookUrl`
  - …9 more
- **2026-10-19** `654c5fc73f4f`: 1 breaking, 8 warning
  - the request property `website` became not nullable
  - removed the request property `description`
  - removed the request property `facebookUrl`
  - removed the request property `instagramUrl`
  - …5 more

[Operation history](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api/changes/companies/post.md)

---

[API](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api.md) · [All operations](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/cavuno/apis/cavuno-v1-rest-api/revisions/d5974dabff14?raw)