# Company Lists
### Company Lists
Company Lists let you build and manage curated sets of companies based on filter criteria such as industry, size, location, and more.
**Typical workflow:**
1. `POST /v1/companies/search` — preview up to 50 companies matching a filter (no list created)
2. `POST /v1/companies/lists` — save the filter as a named list
3. `GET /v1/companies/lists/{listId}/companies` — page through matching companies
4. `PUT /v1/companies/lists/{listId}` — update the list name or filter
5. `DELETE /v1/companies/lists/{listId}` — remove the list
**Caching:** Results are cached for 5 minutes per unique filter and caller. Write operations (create, update, delete) automatically invalidate the cache for the authenticated caller.
## Import a company list from HubSpot
> Create a company list by importing companies directly from a connected\
> HubSpot portal using a property filter.\
> \
> The endpoint queries the HubSpot CRM for companies matching the filter,\
> upserts stub records in Saber so the list is immediately queryable, and\
> returns the created list. Stub records are enriched asynchronously by\
> the normal background pipeline (LinkedIn followers, employee counts,\
> etc.) — this typically completes within minutes to hours depending on\
> queue depth.\
> \
> If some company stubs fail to upsert, those domains are excluded from\
> the list and returned in \`unresolvedDomains\` so callers can surface a\
> warning to the user.\
> \
> \*\*Requires a connected HubSpot installation.\*\* Returns \`400\` if no\
> HubSpot portal is linked to the authenticated organization.
```json
{"openapi":"3.0.3","info":{"title":"Saber Platform API","version":"1.0.0"},"tags":[{"name":"Company Lists","description":"## Company Lists\n\nCompany Lists let you build and manage curated sets of companies based on\nfilter criteria such as industry, size, location, and more.\n\n**Typical workflow:**\n1. `POST /v1/companies/search` — preview up to 50 companies matching a filter (no list created)\n2. `POST /v1/companies/lists` — save the filter as a named list\n3. `GET /v1/companies/lists/{listId}/companies` — page through matching companies\n4. `PUT /v1/companies/lists/{listId}` — update the list name or filter\n5. `DELETE /v1/companies/lists/{listId}` — remove the list\n\n**Caching:** Results are cached for 5 minutes per unique filter and caller.\nWrite operations (create, update, delete) automatically invalidate the cache\nfor the authenticated caller.\n"}],"servers":[{"url":"https://api.saber.app","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"API key authentication using Bearer token. Format: sk_live_ followed by a secure random string."}},"schemas":{"ImportCompanyListRequest":{"type":"object","required":["name","source"],"properties":{"name":{"type":"string","description":"A human-readable name for the imported list (1–200 characters)","minLength":1,"maxLength":200},"source":{"$ref":"#/components/schemas/ImportCompanyListSource"}}},"ImportCompanyListSource":{"type":"object","description":"Describes the external source to import companies from","required":["type","filter"],"properties":{"type":{"type":"string","description":"Import source type. Currently only `hubspot` is supported.","enum":["hubspot"]},"filter":{"$ref":"#/components/schemas/HubSpotPropertyFilter"}}},"HubSpotPropertyFilter":{"type":"object","description":"A single HubSpot property filter used to select companies for import","required":["propertyName","operator"],"properties":{"propertyName":{"type":"string","description":"The HubSpot company property to filter on (e.g. `industry`, `city`, `hs_lead_status`)"},"operator":{"type":"string","description":"Comparison operator. Value-free operators (`HAS_PROPERTY`, `NOT_HAS_PROPERTY`)\ndo not require a `value` field. All others do.\n","enum":["EQ","NEQ","GT","GTE","LT","LTE","HAS_PROPERTY","NOT_HAS_PROPERTY","CONTAINS_TOKEN","NOT_CONTAINS_TOKEN"]},"value":{"type":"string","description":"The value to compare against. Required for all operators except `HAS_PROPERTY` and `NOT_HAS_PROPERTY`."}}},"ImportCompanyListResponse":{"allOf":[{"$ref":"#/components/schemas/CompanyListResponse"},{"type":"object","properties":{"unresolvedDomains":{"type":"array","description":"Domains from the HubSpot result whose stub records could not be\nupserted. These domains are excluded from the list filter.\nPresent only when one or more upserts fail; omitted on full success.\n","items":{"type":"string"}}}}]},"CompanyListResponse":{"type":"object","description":"A saved company list with its filter definition","properties":{"id":{"type":"string","description":"Unique identifier for the list"},"name":{"type":"string","description":"Human-readable list name"},"prompt":{"type":"string","description":"Optional prompt used to generate the filter"},"filter":{"$ref":"#/components/schemas/CompanyListFilters"},"createdAt":{"type":"string","format":"date-time","description":"When the list was created"},"updatedAt":{"type":"string","format":"date-time","description":"When the list was last updated"}},"required":["id","name","filter","createdAt"]},"CompanyListFilters":{"type":"object","description":"Criteria for filtering companies","properties":{"domains":{"type":"array","items":{"type":"string"},"description":"Filter by company domains"},"names":{"type":"array","items":{"type":"string"},"description":"Filter by company names"},"handles":{"type":"array","items":{"type":"string"},"description":"Filter by company handles"},"websites":{"type":"array","items":{"type":"string"},"description":"Filter by company websites"},"industries":{"type":"array","items":{"type":"string"},"description":"Filter by industry names"},"sizes":{"type":"array","items":{"type":"string"},"description":"Filter by company size ranges"},"types":{"type":"array","items":{"type":"string"},"description":"Filter by company types"},"founded":{"type":"object","description":"Filter by founded year range","properties":{"before":{"type":"integer","description":"Founded before this year"},"after":{"type":"integer","description":"Founded after this year"}}},"location":{"type":"object","description":"Filter by geographic location","properties":{"cities":{"type":"array","items":{"type":"string"},"description":"Filter by city names"},"states":{"type":"array","items":{"type":"string"},"description":"Filter by state/province names"},"countryCodes":{"type":"array","items":{"type":"string"},"description":"Filter by ISO country codes"}}},"exclude":{"type":"object","description":"Exclusion filters (companies matching these are removed)","properties":{"industries":{"type":"array","items":{"type":"string"}},"sizes":{"type":"array","items":{"type":"string"}},"types":{"type":"array","items":{"type":"string"}},"domains":{"type":"array","items":{"type":"string"}},"location":{"type":"object","properties":{"cities":{"type":"array","items":{"type":"string"}},"states":{"type":"array","items":{"type":"string"}},"countryCodes":{"type":"array","items":{"type":"string"}}}}}},"questionIds":{"type":"array","items":{"type":"string"},"description":"Filter by signal question IDs"},"technologies":{"type":"array","items":{"type":"string"},"description":"Filter by technology slugs (companies must use at least one of the specified technologies)"}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"array","description":"Additional error details (optional)","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}},"required":["error","message"]}}},"paths":{"/v1/companies/lists/import":{"post":{"tags":["Company Lists"],"summary":"Import a company list from HubSpot","operationId":"importCompanyList","description":"Create a company list by importing companies directly from a connected\nHubSpot portal using a property filter.\n\nThe endpoint queries the HubSpot CRM for companies matching the filter,\nupserts stub records in Saber so the list is immediately queryable, and\nreturns the created list. Stub records are enriched asynchronously by\nthe normal background pipeline (LinkedIn followers, employee counts,\netc.) — this typically completes within minutes to hours depending on\nqueue depth.\n\nIf some company stubs fail to upsert, those domains are excluded from\nthe list and returned in `unresolvedDomains` so callers can surface a\nwarning to the user.\n\n**Requires a connected HubSpot installation.** Returns `400` if no\nHubSpot portal is linked to the authenticated organization.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportCompanyListRequest"}}}},"responses":{"201":{"description":"Company list imported and created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ImportCompanyListResponse"}}}},"400":{"description":"Bad Request — no HubSpot installation connected, or invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized — invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable Entity — filter matched zero companies","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests — rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
## Preview expected company count and credit cost
> Returns the number of companies that match a given filter and the Saber\
> credit cost to create that list — without creating the list or charging\
> any credits.\
> \
> When \`technologies\` is present the count is fetched from Theirstack in\
> blur mode (free), so you can show the user "X companies match, Y credits\
> required" before they commit. For filters without \`technologies\` the\
> count is a fast database query (always free).\
> \
> Results are cached for 5 minutes per caller.
```json
{"openapi":"3.0.3","info":{"title":"Saber Platform API","version":"1.0.0"},"tags":[{"name":"Company Lists","description":"## Company Lists\n\nCompany Lists let you build and manage curated sets of companies based on\nfilter criteria such as industry, size, location, and more.\n\n**Typical workflow:**\n1. `POST /v1/companies/search` — preview up to 50 companies matching a filter (no list created)\n2. `POST /v1/companies/lists` — save the filter as a named list\n3. `GET /v1/companies/lists/{listId}/companies` — page through matching companies\n4. `PUT /v1/companies/lists/{listId}` — update the list name or filter\n5. `DELETE /v1/companies/lists/{listId}` — remove the list\n\n**Caching:** Results are cached for 5 minutes per unique filter and caller.\nWrite operations (create, update, delete) automatically invalidate the cache\nfor the authenticated caller.\n"}],"servers":[{"url":"https://api.saber.app","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"API key authentication using Bearer token. Format: sk_live_ followed by a secure random string."}},"schemas":{"CompanySearchRequest":{"type":"object","required":["filter"],"properties":{"filter":{"$ref":"#/components/schemas/CompanyListFilters"}}},"CompanyListFilters":{"type":"object","description":"Criteria for filtering companies","properties":{"domains":{"type":"array","items":{"type":"string"},"description":"Filter by company domains"},"names":{"type":"array","items":{"type":"string"},"description":"Filter by company names"},"handles":{"type":"array","items":{"type":"string"},"description":"Filter by company handles"},"websites":{"type":"array","items":{"type":"string"},"description":"Filter by company websites"},"industries":{"type":"array","items":{"type":"string"},"description":"Filter by industry names"},"sizes":{"type":"array","items":{"type":"string"},"description":"Filter by company size ranges"},"types":{"type":"array","items":{"type":"string"},"description":"Filter by company types"},"founded":{"type":"object","description":"Filter by founded year range","properties":{"before":{"type":"integer","description":"Founded before this year"},"after":{"type":"integer","description":"Founded after this year"}}},"location":{"type":"object","description":"Filter by geographic location","properties":{"cities":{"type":"array","items":{"type":"string"},"description":"Filter by city names"},"states":{"type":"array","items":{"type":"string"},"description":"Filter by state/province names"},"countryCodes":{"type":"array","items":{"type":"string"},"description":"Filter by ISO country codes"}}},"exclude":{"type":"object","description":"Exclusion filters (companies matching these are removed)","properties":{"industries":{"type":"array","items":{"type":"string"}},"sizes":{"type":"array","items":{"type":"string"}},"types":{"type":"array","items":{"type":"string"}},"domains":{"type":"array","items":{"type":"string"}},"location":{"type":"object","properties":{"cities":{"type":"array","items":{"type":"string"}},"states":{"type":"array","items":{"type":"string"}},"countryCodes":{"type":"array","items":{"type":"string"}}}}}},"questionIds":{"type":"array","items":{"type":"string"},"description":"Filter by signal question IDs"},"technologies":{"type":"array","items":{"type":"string"},"description":"Filter by technology slugs (companies must use at least one of the specified technologies)"}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"array","description":"Additional error details (optional)","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}},"required":["error","message"]}}},"paths":{"/v1/companies/lists/count-preview":{"post":{"tags":["Company Lists"],"summary":"Preview expected company count and credit cost","operationId":"countPreviewCompanyList","description":"Returns the number of companies that match a given filter and the Saber\ncredit cost to create that list — without creating the list or charging\nany credits.\n\nWhen `technologies` is present the count is fetched from Theirstack in\nblur mode (free), so you can show the user \"X companies match, Y credits\nrequired\" before they commit. For filters without `technologies` the\ncount is a fast database query (always free).\n\nResults are cached for 5 minutes per caller.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanySearchRequest"}}}},"responses":{"200":{"description":"Count and credit cost returned successfully","content":{"application/json":{"schema":{"type":"object","required":["count","credits"],"properties":{"count":{"type":"integer","description":"Number of companies expected to match the filter"},"credits":{"type":"integer","description":"Saber credits that will be charged when the list is created"}}}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
## List all company lists
> Retrieve a paginated list of company lists belonging to the authenticated caller.
```json
{"openapi":"3.0.3","info":{"title":"Saber Platform API","version":"1.0.0"},"tags":[{"name":"Company Lists","description":"## Company Lists\n\nCompany Lists let you build and manage curated sets of companies based on\nfilter criteria such as industry, size, location, and more.\n\n**Typical workflow:**\n1. `POST /v1/companies/search` — preview up to 50 companies matching a filter (no list created)\n2. `POST /v1/companies/lists` — save the filter as a named list\n3. `GET /v1/companies/lists/{listId}/companies` — page through matching companies\n4. `PUT /v1/companies/lists/{listId}` — update the list name or filter\n5. `DELETE /v1/companies/lists/{listId}` — remove the list\n\n**Caching:** Results are cached for 5 minutes per unique filter and caller.\nWrite operations (create, update, delete) automatically invalidate the cache\nfor the authenticated caller.\n"}],"servers":[{"url":"https://api.saber.app","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"API key authentication using Bearer token. Format: sk_live_ followed by a secure random string."}},"schemas":{"CompanyListsResponse":{"type":"object","description":"Paginated list of company lists","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CompanyListResponse"}},"total":{"type":"integer","description":"Total number of lists"},"limit":{"type":"integer","description":"Maximum results per page"},"offset":{"type":"integer","description":"Number of results skipped"},"hasMore":{"type":"boolean","description":"Whether more results are available"}},"required":["items","total","limit","offset","hasMore"]},"CompanyListResponse":{"type":"object","description":"A saved company list with its filter definition","properties":{"id":{"type":"string","description":"Unique identifier for the list"},"name":{"type":"string","description":"Human-readable list name"},"prompt":{"type":"string","description":"Optional prompt used to generate the filter"},"filter":{"$ref":"#/components/schemas/CompanyListFilters"},"createdAt":{"type":"string","format":"date-time","description":"When the list was created"},"updatedAt":{"type":"string","format":"date-time","description":"When the list was last updated"}},"required":["id","name","filter","createdAt"]},"CompanyListFilters":{"type":"object","description":"Criteria for filtering companies","properties":{"domains":{"type":"array","items":{"type":"string"},"description":"Filter by company domains"},"names":{"type":"array","items":{"type":"string"},"description":"Filter by company names"},"handles":{"type":"array","items":{"type":"string"},"description":"Filter by company handles"},"websites":{"type":"array","items":{"type":"string"},"description":"Filter by company websites"},"industries":{"type":"array","items":{"type":"string"},"description":"Filter by industry names"},"sizes":{"type":"array","items":{"type":"string"},"description":"Filter by company size ranges"},"types":{"type":"array","items":{"type":"string"},"description":"Filter by company types"},"founded":{"type":"object","description":"Filter by founded year range","properties":{"before":{"type":"integer","description":"Founded before this year"},"after":{"type":"integer","description":"Founded after this year"}}},"location":{"type":"object","description":"Filter by geographic location","properties":{"cities":{"type":"array","items":{"type":"string"},"description":"Filter by city names"},"states":{"type":"array","items":{"type":"string"},"description":"Filter by state/province names"},"countryCodes":{"type":"array","items":{"type":"string"},"description":"Filter by ISO country codes"}}},"exclude":{"type":"object","description":"Exclusion filters (companies matching these are removed)","properties":{"industries":{"type":"array","items":{"type":"string"}},"sizes":{"type":"array","items":{"type":"string"}},"types":{"type":"array","items":{"type":"string"}},"domains":{"type":"array","items":{"type":"string"}},"location":{"type":"object","properties":{"cities":{"type":"array","items":{"type":"string"}},"states":{"type":"array","items":{"type":"string"}},"countryCodes":{"type":"array","items":{"type":"string"}}}}}},"questionIds":{"type":"array","items":{"type":"string"},"description":"Filter by signal question IDs"},"technologies":{"type":"array","items":{"type":"string"},"description":"Filter by technology slugs (companies must use at least one of the specified technologies)"}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"array","description":"Additional error details (optional)","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}},"required":["error","message"]}}},"paths":{"/v1/companies/lists":{"get":{"tags":["Company Lists"],"summary":"List all company lists","operationId":"listCompanyLists","description":"Retrieve a paginated list of company lists belonging to the authenticated caller.\n","parameters":[{"name":"limit","in":"query","description":"Maximum number of lists to return (1–100, default 20)","schema":{"type":"integer","minimum":1,"maximum":100,"default":20}},{"name":"offset","in":"query","description":"Number of lists to skip for pagination (default 0)","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Company lists retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyListsResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
## Create a company list
> Create a named company list with a filter definition. The filter criteria\
> determine which companies belong to the list.\
> \
> Results are cached for 5 minutes per caller. Mutations (create, update,\
> delete) automatically invalidate the cache for the authenticated caller.
```json
{"openapi":"3.0.3","info":{"title":"Saber Platform API","version":"1.0.0"},"tags":[{"name":"Company Lists","description":"## Company Lists\n\nCompany Lists let you build and manage curated sets of companies based on\nfilter criteria such as industry, size, location, and more.\n\n**Typical workflow:**\n1. `POST /v1/companies/search` — preview up to 50 companies matching a filter (no list created)\n2. `POST /v1/companies/lists` — save the filter as a named list\n3. `GET /v1/companies/lists/{listId}/companies` — page through matching companies\n4. `PUT /v1/companies/lists/{listId}` — update the list name or filter\n5. `DELETE /v1/companies/lists/{listId}` — remove the list\n\n**Caching:** Results are cached for 5 minutes per unique filter and caller.\nWrite operations (create, update, delete) automatically invalidate the cache\nfor the authenticated caller.\n"}],"servers":[{"url":"https://api.saber.app","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"API key authentication using Bearer token. Format: sk_live_ followed by a secure random string."}},"schemas":{"CreateCompanyListRequest":{"type":"object","required":["name","filter"],"properties":{"name":{"type":"string","description":"A human-readable name for the list (1–200 characters)","minLength":1,"maxLength":200},"filter":{"$ref":"#/components/schemas/CompanyListFilters"}}},"CompanyListFilters":{"type":"object","description":"Criteria for filtering companies","properties":{"domains":{"type":"array","items":{"type":"string"},"description":"Filter by company domains"},"names":{"type":"array","items":{"type":"string"},"description":"Filter by company names"},"handles":{"type":"array","items":{"type":"string"},"description":"Filter by company handles"},"websites":{"type":"array","items":{"type":"string"},"description":"Filter by company websites"},"industries":{"type":"array","items":{"type":"string"},"description":"Filter by industry names"},"sizes":{"type":"array","items":{"type":"string"},"description":"Filter by company size ranges"},"types":{"type":"array","items":{"type":"string"},"description":"Filter by company types"},"founded":{"type":"object","description":"Filter by founded year range","properties":{"before":{"type":"integer","description":"Founded before this year"},"after":{"type":"integer","description":"Founded after this year"}}},"location":{"type":"object","description":"Filter by geographic location","properties":{"cities":{"type":"array","items":{"type":"string"},"description":"Filter by city names"},"states":{"type":"array","items":{"type":"string"},"description":"Filter by state/province names"},"countryCodes":{"type":"array","items":{"type":"string"},"description":"Filter by ISO country codes"}}},"exclude":{"type":"object","description":"Exclusion filters (companies matching these are removed)","properties":{"industries":{"type":"array","items":{"type":"string"}},"sizes":{"type":"array","items":{"type":"string"}},"types":{"type":"array","items":{"type":"string"}},"domains":{"type":"array","items":{"type":"string"}},"location":{"type":"object","properties":{"cities":{"type":"array","items":{"type":"string"}},"states":{"type":"array","items":{"type":"string"}},"countryCodes":{"type":"array","items":{"type":"string"}}}}}},"questionIds":{"type":"array","items":{"type":"string"},"description":"Filter by signal question IDs"},"technologies":{"type":"array","items":{"type":"string"},"description":"Filter by technology slugs (companies must use at least one of the specified technologies)"}}},"CompanyListResponse":{"type":"object","description":"A saved company list with its filter definition","properties":{"id":{"type":"string","description":"Unique identifier for the list"},"name":{"type":"string","description":"Human-readable list name"},"prompt":{"type":"string","description":"Optional prompt used to generate the filter"},"filter":{"$ref":"#/components/schemas/CompanyListFilters"},"createdAt":{"type":"string","format":"date-time","description":"When the list was created"},"updatedAt":{"type":"string","format":"date-time","description":"When the list was last updated"}},"required":["id","name","filter","createdAt"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"array","description":"Additional error details (optional)","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}},"required":["error","message"]}}},"paths":{"/v1/companies/lists":{"post":{"tags":["Company Lists"],"summary":"Create a company list","operationId":"createCompanyList","description":"Create a named company list with a filter definition. The filter criteria\ndetermine which companies belong to the list.\n\nResults are cached for 5 minutes per caller. Mutations (create, update,\ndelete) automatically invalidate the cache for the authenticated caller.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateCompanyListRequest"}}}},"responses":{"201":{"description":"Company list created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyListResponse"}}}},"400":{"description":"Bad Request - Invalid parameters (e.g. empty or too-long name)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
## Get a company list by ID
> Retrieve a single company list including its name and filter definition.
```json
{"openapi":"3.0.3","info":{"title":"Saber Platform API","version":"1.0.0"},"tags":[{"name":"Company Lists","description":"## Company Lists\n\nCompany Lists let you build and manage curated sets of companies based on\nfilter criteria such as industry, size, location, and more.\n\n**Typical workflow:**\n1. `POST /v1/companies/search` — preview up to 50 companies matching a filter (no list created)\n2. `POST /v1/companies/lists` — save the filter as a named list\n3. `GET /v1/companies/lists/{listId}/companies` — page through matching companies\n4. `PUT /v1/companies/lists/{listId}` — update the list name or filter\n5. `DELETE /v1/companies/lists/{listId}` — remove the list\n\n**Caching:** Results are cached for 5 minutes per unique filter and caller.\nWrite operations (create, update, delete) automatically invalidate the cache\nfor the authenticated caller.\n"}],"servers":[{"url":"https://api.saber.app","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"API key authentication using Bearer token. Format: sk_live_ followed by a secure random string."}},"schemas":{"CompanyListResponse":{"type":"object","description":"A saved company list with its filter definition","properties":{"id":{"type":"string","description":"Unique identifier for the list"},"name":{"type":"string","description":"Human-readable list name"},"prompt":{"type":"string","description":"Optional prompt used to generate the filter"},"filter":{"$ref":"#/components/schemas/CompanyListFilters"},"createdAt":{"type":"string","format":"date-time","description":"When the list was created"},"updatedAt":{"type":"string","format":"date-time","description":"When the list was last updated"}},"required":["id","name","filter","createdAt"]},"CompanyListFilters":{"type":"object","description":"Criteria for filtering companies","properties":{"domains":{"type":"array","items":{"type":"string"},"description":"Filter by company domains"},"names":{"type":"array","items":{"type":"string"},"description":"Filter by company names"},"handles":{"type":"array","items":{"type":"string"},"description":"Filter by company handles"},"websites":{"type":"array","items":{"type":"string"},"description":"Filter by company websites"},"industries":{"type":"array","items":{"type":"string"},"description":"Filter by industry names"},"sizes":{"type":"array","items":{"type":"string"},"description":"Filter by company size ranges"},"types":{"type":"array","items":{"type":"string"},"description":"Filter by company types"},"founded":{"type":"object","description":"Filter by founded year range","properties":{"before":{"type":"integer","description":"Founded before this year"},"after":{"type":"integer","description":"Founded after this year"}}},"location":{"type":"object","description":"Filter by geographic location","properties":{"cities":{"type":"array","items":{"type":"string"},"description":"Filter by city names"},"states":{"type":"array","items":{"type":"string"},"description":"Filter by state/province names"},"countryCodes":{"type":"array","items":{"type":"string"},"description":"Filter by ISO country codes"}}},"exclude":{"type":"object","description":"Exclusion filters (companies matching these are removed)","properties":{"industries":{"type":"array","items":{"type":"string"}},"sizes":{"type":"array","items":{"type":"string"}},"types":{"type":"array","items":{"type":"string"}},"domains":{"type":"array","items":{"type":"string"}},"location":{"type":"object","properties":{"cities":{"type":"array","items":{"type":"string"}},"states":{"type":"array","items":{"type":"string"}},"countryCodes":{"type":"array","items":{"type":"string"}}}}}},"questionIds":{"type":"array","items":{"type":"string"},"description":"Filter by signal question IDs"},"technologies":{"type":"array","items":{"type":"string"},"description":"Filter by technology slugs (companies must use at least one of the specified technologies)"}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"array","description":"Additional error details (optional)","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}},"required":["error","message"]}}},"paths":{"/v1/companies/lists/{listId}":{"get":{"tags":["Company Lists"],"summary":"Get a company list by ID","operationId":"getCompanyList","description":"Retrieve a single company list including its name and filter definition.","parameters":[{"name":"listId","in":"path","required":true,"description":"The unique identifier of the company list","schema":{"type":"string"}}],"responses":{"200":{"description":"Company list retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyListResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Company list not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
## Update a company list
> Update the name and/or filter of an existing company list. Both fields\
> are required in the request body (full replacement, not a patch).
```json
{"openapi":"3.0.3","info":{"title":"Saber Platform API","version":"1.0.0"},"tags":[{"name":"Company Lists","description":"## Company Lists\n\nCompany Lists let you build and manage curated sets of companies based on\nfilter criteria such as industry, size, location, and more.\n\n**Typical workflow:**\n1. `POST /v1/companies/search` — preview up to 50 companies matching a filter (no list created)\n2. `POST /v1/companies/lists` — save the filter as a named list\n3. `GET /v1/companies/lists/{listId}/companies` — page through matching companies\n4. `PUT /v1/companies/lists/{listId}` — update the list name or filter\n5. `DELETE /v1/companies/lists/{listId}` — remove the list\n\n**Caching:** Results are cached for 5 minutes per unique filter and caller.\nWrite operations (create, update, delete) automatically invalidate the cache\nfor the authenticated caller.\n"}],"servers":[{"url":"https://api.saber.app","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"API key authentication using Bearer token. Format: sk_live_ followed by a secure random string."}},"schemas":{"UpdateCompanyListRequest":{"type":"object","required":["name","filter"],"properties":{"name":{"type":"string","description":"Updated name for the list (1–200 characters)","minLength":1,"maxLength":200},"filter":{"$ref":"#/components/schemas/CompanyListFilters"}}},"CompanyListFilters":{"type":"object","description":"Criteria for filtering companies","properties":{"domains":{"type":"array","items":{"type":"string"},"description":"Filter by company domains"},"names":{"type":"array","items":{"type":"string"},"description":"Filter by company names"},"handles":{"type":"array","items":{"type":"string"},"description":"Filter by company handles"},"websites":{"type":"array","items":{"type":"string"},"description":"Filter by company websites"},"industries":{"type":"array","items":{"type":"string"},"description":"Filter by industry names"},"sizes":{"type":"array","items":{"type":"string"},"description":"Filter by company size ranges"},"types":{"type":"array","items":{"type":"string"},"description":"Filter by company types"},"founded":{"type":"object","description":"Filter by founded year range","properties":{"before":{"type":"integer","description":"Founded before this year"},"after":{"type":"integer","description":"Founded after this year"}}},"location":{"type":"object","description":"Filter by geographic location","properties":{"cities":{"type":"array","items":{"type":"string"},"description":"Filter by city names"},"states":{"type":"array","items":{"type":"string"},"description":"Filter by state/province names"},"countryCodes":{"type":"array","items":{"type":"string"},"description":"Filter by ISO country codes"}}},"exclude":{"type":"object","description":"Exclusion filters (companies matching these are removed)","properties":{"industries":{"type":"array","items":{"type":"string"}},"sizes":{"type":"array","items":{"type":"string"}},"types":{"type":"array","items":{"type":"string"}},"domains":{"type":"array","items":{"type":"string"}},"location":{"type":"object","properties":{"cities":{"type":"array","items":{"type":"string"}},"states":{"type":"array","items":{"type":"string"}},"countryCodes":{"type":"array","items":{"type":"string"}}}}}},"questionIds":{"type":"array","items":{"type":"string"},"description":"Filter by signal question IDs"},"technologies":{"type":"array","items":{"type":"string"},"description":"Filter by technology slugs (companies must use at least one of the specified technologies)"}}},"CompanyListResponse":{"type":"object","description":"A saved company list with its filter definition","properties":{"id":{"type":"string","description":"Unique identifier for the list"},"name":{"type":"string","description":"Human-readable list name"},"prompt":{"type":"string","description":"Optional prompt used to generate the filter"},"filter":{"$ref":"#/components/schemas/CompanyListFilters"},"createdAt":{"type":"string","format":"date-time","description":"When the list was created"},"updatedAt":{"type":"string","format":"date-time","description":"When the list was last updated"}},"required":["id","name","filter","createdAt"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"array","description":"Additional error details (optional)","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}},"required":["error","message"]}}},"paths":{"/v1/companies/lists/{listId}":{"put":{"tags":["Company Lists"],"summary":"Update a company list","operationId":"updateCompanyList","description":"Update the name and/or filter of an existing company list. Both fields\nare required in the request body (full replacement, not a patch).\n","parameters":[{"name":"listId","in":"path","required":true,"description":"The unique identifier of the company list to update","schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UpdateCompanyListRequest"}}}},"responses":{"200":{"description":"Company list updated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyListResponse"}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Company list not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
## Delete a company list
> Soft-delete a company list. The list will no longer appear in list\
> results. This operation cannot be undone via the API.
```json
{"openapi":"3.0.3","info":{"title":"Saber Platform API","version":"1.0.0"},"tags":[{"name":"Company Lists","description":"## Company Lists\n\nCompany Lists let you build and manage curated sets of companies based on\nfilter criteria such as industry, size, location, and more.\n\n**Typical workflow:**\n1. `POST /v1/companies/search` — preview up to 50 companies matching a filter (no list created)\n2. `POST /v1/companies/lists` — save the filter as a named list\n3. `GET /v1/companies/lists/{listId}/companies` — page through matching companies\n4. `PUT /v1/companies/lists/{listId}` — update the list name or filter\n5. `DELETE /v1/companies/lists/{listId}` — remove the list\n\n**Caching:** Results are cached for 5 minutes per unique filter and caller.\nWrite operations (create, update, delete) automatically invalidate the cache\nfor the authenticated caller.\n"}],"servers":[{"url":"https://api.saber.app","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"API key authentication using Bearer token. Format: sk_live_ followed by a secure random string."}},"schemas":{"ErrorResponse":{"type":"object","properties":{"error":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"array","description":"Additional error details (optional)","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}},"required":["error","message"]}}},"paths":{"/v1/companies/lists/{listId}":{"delete":{"tags":["Company Lists"],"summary":"Delete a company list","operationId":"deleteCompanyList","description":"Soft-delete a company list. The list will no longer appear in list\nresults. This operation cannot be undone via the API.\n","parameters":[{"name":"listId","in":"path","required":true,"description":"The unique identifier of the company list to delete","schema":{"type":"string"}}],"responses":{"204":{"description":"Company list deleted successfully"},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Company list not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
## Get companies in a list
> Retrieve companies that belong to a company list, paginated. Companies\
> are returned with basic profile information and optional LinkedIn\
> enrichment data.
```json
{"openapi":"3.0.3","info":{"title":"Saber Platform API","version":"1.0.0"},"tags":[{"name":"Company Lists","description":"## Company Lists\n\nCompany Lists let you build and manage curated sets of companies based on\nfilter criteria such as industry, size, location, and more.\n\n**Typical workflow:**\n1. `POST /v1/companies/search` — preview up to 50 companies matching a filter (no list created)\n2. `POST /v1/companies/lists` — save the filter as a named list\n3. `GET /v1/companies/lists/{listId}/companies` — page through matching companies\n4. `PUT /v1/companies/lists/{listId}` — update the list name or filter\n5. `DELETE /v1/companies/lists/{listId}` — remove the list\n\n**Caching:** Results are cached for 5 minutes per unique filter and caller.\nWrite operations (create, update, delete) automatically invalidate the cache\nfor the authenticated caller.\n"}],"servers":[{"url":"https://api.saber.app","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"API key authentication using Bearer token. Format: sk_live_ followed by a secure random string."}},"schemas":{"CompanyListCompaniesResponse":{"type":"object","description":"Paginated list of companies in a company list","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/CompanyListCompany"}},"total":{"type":"integer","description":"Total number of companies in the list"},"limit":{"type":"integer","description":"Maximum results per page"},"offset":{"type":"integer","description":"Number of results skipped"},"hasMore":{"type":"boolean","description":"Whether more results are available"}},"required":["items","total","limit","offset","hasMore"]},"CompanyListCompany":{"type":"object","description":"A company matching the search filter","properties":{"id":{"type":"string","description":"Unique company identifier"},"domain":{"type":"string","description":"Company domain"},"name":{"type":"string","description":"Company name"},"handle":{"type":"string","description":"Company handle"},"website":{"type":"string","description":"Company website URL"},"industry":{"type":"string","description":"Industry classification"},"size":{"type":"string","description":"Company size range"},"type":{"type":"string","description":"Company type"},"founded":{"type":"integer","description":"Year the company was founded"},"city":{"type":"string","description":"City name"},"state":{"type":"string","description":"State/province name"},"countryCode":{"type":"string","description":"ISO country code"},"enrichedData":{"type":"object","description":"LinkedIn enrichment data","properties":{"liId":{"type":"integer","description":"LinkedIn company ID"},"liFollowers":{"type":"integer","description":"Number of LinkedIn followers"},"liFoundEmployees":{"type":"integer","description":"Number of employees found on LinkedIn"}}}},"required":["id","domain","name"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"array","description":"Additional error details (optional)","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}},"required":["error","message"]}}},"paths":{"/v1/companies/lists/{listId}/companies":{"get":{"tags":["Company Lists"],"summary":"Get companies in a list","operationId":"getCompanyListCompanies","description":"Retrieve companies that belong to a company list, paginated. Companies\nare returned with basic profile information and optional LinkedIn\nenrichment data.\n","parameters":[{"name":"listId","in":"path","required":true,"description":"The unique identifier of the company list","schema":{"type":"string"}},{"name":"limit","in":"query","description":"Maximum number of companies to return (1–100, default 25)","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"offset","in":"query","description":"Number of companies to skip for pagination (default 0)","schema":{"type":"integer","minimum":0,"default":0}}],"responses":{"200":{"description":"Companies retrieved successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyListCompaniesResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Company list not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
## Export a company list as CSV
> Export all companies in a list as a CSV file. Returns a\
> \`text/csv\` file with one row per company.\
> \
> \*\*Fixed columns\*\* (always present): \`name\`, \`website\`\
> \
> \*\*Optional firmographic columns\*\* — specify via the \`fields\` array in\
> any order. Allowed values: \`industry\`, \`size\`, \`founded\`, \`city\`,\
> \`state\`, \`country\_code\`. Unknown values return 422.\
> \
> \*\*Signal columns\*\* — specify \`signalTemplateIds\` to include two\
> columns per matching subscription: \`{signal\_name}\_answer\` and\
> \`{signal\_name}\_confidence\`. If \`signalTemplateIds\` is absent or empty,\
> no signal columns are added.\
> \
> The export is truncated to the first 10,000 companies. No credits are charged.
```json
{"openapi":"3.0.3","info":{"title":"Saber Platform API","version":"1.0.0"},"tags":[{"name":"Company Lists","description":"## Company Lists\n\nCompany Lists let you build and manage curated sets of companies based on\nfilter criteria such as industry, size, location, and more.\n\n**Typical workflow:**\n1. `POST /v1/companies/search` — preview up to 50 companies matching a filter (no list created)\n2. `POST /v1/companies/lists` — save the filter as a named list\n3. `GET /v1/companies/lists/{listId}/companies` — page through matching companies\n4. `PUT /v1/companies/lists/{listId}` — update the list name or filter\n5. `DELETE /v1/companies/lists/{listId}` — remove the list\n\n**Caching:** Results are cached for 5 minutes per unique filter and caller.\nWrite operations (create, update, delete) automatically invalidate the cache\nfor the authenticated caller.\n"}],"servers":[{"url":"https://api.saber.app","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"API key authentication using Bearer token. Format: sk_live_ followed by a secure random string."}},"schemas":{"ExportCompanyListRequest":{"type":"object","description":"Optional parameters for the company list CSV export.","properties":{"fields":{"type":"array","items":{"type":"string","enum":["industry","size","founded","city","state","country_code"]},"description":"Optional firmographic columns to include after the fixed `name` and\n`website` columns, in the order specified. Unknown values return 422.\n"},"signalTemplateIds":{"type":"array","items":{"type":"string","format":"uuid"},"description":"IDs of signal templates whose subscriptions should be included as\ncolumns. Two columns are added per subscription:\n`{signal_name}_answer` and `{signal_name}_confidence`. If absent\nor empty, no signal columns are added.\n"}}},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"array","description":"Additional error details (optional)","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}},"required":["error","message"]}}},"paths":{"/v1/companies/lists/{listId}/export":{"post":{"tags":["Company Lists"],"summary":"Export a company list as CSV","operationId":"exportCompanyList","description":"Export all companies in a list as a CSV file. Returns a\n`text/csv` file with one row per company.\n\n**Fixed columns** (always present): `name`, `website`\n\n**Optional firmographic columns** — specify via the `fields` array in\nany order. Allowed values: `industry`, `size`, `founded`, `city`,\n`state`, `country_code`. Unknown values return 422.\n\n**Signal columns** — specify `signalTemplateIds` to include two\ncolumns per matching subscription: `{signal_name}_answer` and\n`{signal_name}_confidence`. If `signalTemplateIds` is absent or empty,\nno signal columns are added.\n\nThe export is truncated to the first 10,000 companies. No credits are charged.\n","parameters":[{"name":"listId","in":"path","required":true,"description":"The unique identifier of the company list","schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ExportCompanyListRequest"}}}},"responses":{"200":{"description":"CSV file streamed successfully","content":{"text/csv":{"schema":{"type":"string","format":"binary"}}},"headers":{"Content-Disposition":{"description":"Attachment filename derived from the list name","schema":{"type":"string"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Company list not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable Entity - Invalid field name or list exceeds 10,000 companies","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```
## Search companies matching a filter
> Returns up to 50 companies that match the given filter criteria.\
> \
> Results are cached for 5 minutes per unique filter. Identical filters\
> will return cached data during this window.
```json
{"openapi":"3.0.3","info":{"title":"Saber Platform API","version":"1.0.0"},"tags":[{"name":"Company Lists","description":"## Company Lists\n\nCompany Lists let you build and manage curated sets of companies based on\nfilter criteria such as industry, size, location, and more.\n\n**Typical workflow:**\n1. `POST /v1/companies/search` — preview up to 50 companies matching a filter (no list created)\n2. `POST /v1/companies/lists` — save the filter as a named list\n3. `GET /v1/companies/lists/{listId}/companies` — page through matching companies\n4. `PUT /v1/companies/lists/{listId}` — update the list name or filter\n5. `DELETE /v1/companies/lists/{listId}` — remove the list\n\n**Caching:** Results are cached for 5 minutes per unique filter and caller.\nWrite operations (create, update, delete) automatically invalidate the cache\nfor the authenticated caller.\n"}],"servers":[{"url":"https://api.saber.app","description":"Production server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"API Key","description":"API key authentication using Bearer token. Format: sk_live_ followed by a secure random string."}},"schemas":{"CompanySearchRequest":{"type":"object","required":["filter"],"properties":{"filter":{"$ref":"#/components/schemas/CompanyListFilters"}}},"CompanyListFilters":{"type":"object","description":"Criteria for filtering companies","properties":{"domains":{"type":"array","items":{"type":"string"},"description":"Filter by company domains"},"names":{"type":"array","items":{"type":"string"},"description":"Filter by company names"},"handles":{"type":"array","items":{"type":"string"},"description":"Filter by company handles"},"websites":{"type":"array","items":{"type":"string"},"description":"Filter by company websites"},"industries":{"type":"array","items":{"type":"string"},"description":"Filter by industry names"},"sizes":{"type":"array","items":{"type":"string"},"description":"Filter by company size ranges"},"types":{"type":"array","items":{"type":"string"},"description":"Filter by company types"},"founded":{"type":"object","description":"Filter by founded year range","properties":{"before":{"type":"integer","description":"Founded before this year"},"after":{"type":"integer","description":"Founded after this year"}}},"location":{"type":"object","description":"Filter by geographic location","properties":{"cities":{"type":"array","items":{"type":"string"},"description":"Filter by city names"},"states":{"type":"array","items":{"type":"string"},"description":"Filter by state/province names"},"countryCodes":{"type":"array","items":{"type":"string"},"description":"Filter by ISO country codes"}}},"exclude":{"type":"object","description":"Exclusion filters (companies matching these are removed)","properties":{"industries":{"type":"array","items":{"type":"string"}},"sizes":{"type":"array","items":{"type":"string"}},"types":{"type":"array","items":{"type":"string"}},"domains":{"type":"array","items":{"type":"string"}},"location":{"type":"object","properties":{"cities":{"type":"array","items":{"type":"string"}},"states":{"type":"array","items":{"type":"string"}},"countryCodes":{"type":"array","items":{"type":"string"}}}}}},"questionIds":{"type":"array","items":{"type":"string"},"description":"Filter by signal question IDs"},"technologies":{"type":"array","items":{"type":"string"},"description":"Filter by technology slugs (companies must use at least one of the specified technologies)"}}},"CompanySearchResponse":{"type":"object","properties":{"companies":{"type":"array","items":{"$ref":"#/components/schemas/CompanyListCompany"},"description":"Up to 50 companies matching the filter"},"total":{"type":"integer","description":"Total number of companies matching the filter"}},"required":["companies","total"]},"CompanyListCompany":{"type":"object","description":"A company matching the search filter","properties":{"id":{"type":"string","description":"Unique company identifier"},"domain":{"type":"string","description":"Company domain"},"name":{"type":"string","description":"Company name"},"handle":{"type":"string","description":"Company handle"},"website":{"type":"string","description":"Company website URL"},"industry":{"type":"string","description":"Industry classification"},"size":{"type":"string","description":"Company size range"},"type":{"type":"string","description":"Company type"},"founded":{"type":"integer","description":"Year the company was founded"},"city":{"type":"string","description":"City name"},"state":{"type":"string","description":"State/province name"},"countryCode":{"type":"string","description":"ISO country code"},"enrichedData":{"type":"object","description":"LinkedIn enrichment data","properties":{"liId":{"type":"integer","description":"LinkedIn company ID"},"liFollowers":{"type":"integer","description":"Number of LinkedIn followers"},"liFoundEmployees":{"type":"integer","description":"Number of employees found on LinkedIn"}}}},"required":["id","domain","name"]},"ErrorResponse":{"type":"object","properties":{"error":{"type":"string","description":"Error code"},"message":{"type":"string","description":"Human-readable error message"},"details":{"type":"array","description":"Additional error details (optional)","items":{"type":"object","properties":{"field":{"type":"string"},"message":{"type":"string"}}}}},"required":["error","message"]}}},"paths":{"/v1/companies/search":{"post":{"tags":["Company Lists"],"summary":"Search companies matching a filter","operationId":"searchCompanies","description":"Returns up to 50 companies that match the given filter criteria.\n\nResults are cached for 5 minutes per unique filter. Identical filters\nwill return cached data during this window.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanySearchRequest"}}}},"responses":{"200":{"description":"Companies matching the filter","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanySearchResponse"}}}},"400":{"description":"Bad Request - Invalid filter parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal Server Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}}}
```