> ## Documentation Index
> Fetch the complete documentation index at: https://docs.breakcold.com/llms.txt
> Use this file to discover all available pages before exploring further.
# List records
> List or search records in one workspace and object type.
Search modes:
- `searchScope=display` (default) searches only the record display name. This preserves the original API behavior and is best when you want a precise name lookup.
- `searchScope=all` searches the display name plus indexed text-like field values on the record: text, textarea, email, phone, URL/social fields, location, select, and multiselect labels. It does not search notes, tasks, conversations, relation target names, numbers, dates, booleans, members, or files.
Token cost
Rate limit
20 tokens
120 requests/min per route/org
## OpenAPI
````yaml /api/openapi.json get /records
openapi: 3.1.0
info:
title: Breakcold Public API
version: 1.0.0
description: >-
Contract-first public API for Breakcold records, tasks, notes, inbox, and
MCP tools.
servers:
- url: https://rest.breakcold.com/api/v1
description: Universal endpoint (routes to your region automatically)
security: []
tags:
- name: Workspaces
- name: CRM
- name: Records
- name: Tasks
- name: Notes
- name: Inbox
- name: Meetings
- name: Webhooks
paths:
/records:
get:
tags:
- Records
summary: List records
description: >-
List or search records in one workspace and object type.
Search modes:
- `searchScope=display` (default) searches only the record display name.
This preserves the original API behavior and is best when you want a
precise name lookup.
- `searchScope=all` searches the display name plus indexed text-like
field values on the record: text, textarea, email, phone, URL/social
fields, location, select, and multiselect labels. It does not search
notes, tasks, conversations, relation target names, numbers, dates,
booleans, members, or files.
Token cost
Rate limit
20 tokens
120 requests/min per route/org
operationId: listRecords
parameters:
- name: X-Breakcold-Organization-Id
in: header
required: false
schema:
type: string
description: >-
Breakcold organization ID. API keys already carry their
organization, so most API-key requests do not need this header. Use
it only when Breakcold asks you to choose an organization for a
signed-in user token.
- name: limit
in: query
required: false
schema:
type: integer
minimum: 1
maximum: 100
default: 50
- name: cursor
in: query
required: false
schema:
type: string
- name: workspaceId
in: query
required: false
schema:
type: string
minLength: 6
- name: objectTypeId
in: query
required: false
schema:
type: string
minLength: 6
- name: objectTypeSlug
in: query
required: false
schema:
type: string
- name: viewId
in: query
required: false
schema:
type: string
minLength: 6
- name: archived
in: query
required: false
schema:
type: boolean
default: false
- name: search
in: query
required: false
description: >-
Search text. By default this matches the record display name only;
set `searchScope=all` to also search indexed text-like field values.
schema:
type: string
- name: searchScope
in: query
required: false
description: >-
`display` searches only record display names. `all` searches display
names plus indexed text-like field values: text, textarea, email,
phone, URL/social fields, location, select, and multiselect labels.
schema:
type: string
enum:
- display
- all
default: display
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
id:
type: string
minLength: 6
workspaceId:
type: string
minLength: 6
objectTypeId:
type: string
minLength: 6
objectTypeSlug:
type: string
displayName:
type: string
fields:
type: object
additionalProperties: true
description: >-
Map of field slug to value. Values follow the field
type: strings for text/social fields, numbers for
numeric/date fields, booleans for checkbox, {
amount, currencyCode } for currency, { optionId }
for select, arrays for multi-value fields.
Multiselect fields accept an array of raw option ids
or { optionId } objects.
isArchived:
type: boolean
createdAt:
type: number
description: Unix timestamp in ms.
updatedAt:
type: number
description: Unix timestamp in ms.
archivedAt:
type: number
description: Unix timestamp in ms.
required:
- id
- workspaceId
- objectTypeId
- isArchived
- createdAt
- updatedAt
pagination:
type: object
properties:
cursor:
type:
- string
- 'null'
hasMore:
type: boolean
required:
- cursor
- hasMore
required:
- data
- pagination
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/RateLimited'
security:
- ApiKeyBearer:
- records:read
- BreakcoldOAuth:
- records:read
components:
responses:
BadRequest:
description: Invalid request
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiError'
Unauthorized:
description: Missing or invalid authentication
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiError'
Forbidden:
description: Authenticated actor cannot access this route or workspace
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiError'
NotFound:
description: Resource not found
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiError'
RateLimited:
description: Rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/PublicApiError'
schemas:
PublicApiError:
type: object
properties:
error:
type: object
properties:
code:
type: string
message:
type: string
requestId:
type: string
details: {}
retryAfterMs:
type: number
required:
- code
- message
- requestId
required:
- error
securitySchemes:
ApiKeyBearer:
type: http
scheme: bearer
description: Breakcold public API key, for example `Bearer bc_live_...`.
BreakcoldOAuth:
type: oauth2
description: >-
Breakcold signed-in user access token. Most REST API integrations should
use an API key instead.
flows:
authorizationCode:
authorizationUrl: https://YOUR_AUTH_DOMAIN/oauth2/authorize
tokenUrl: https://YOUR_AUTH_DOMAIN/oauth2/token
scopes:
records:read: Access records:read
records:write: Access records:write
tasks:read: Access tasks:read
tasks:write: Access tasks:write
notes:read: Access notes:read
notes:write: Access notes:write
inbox:read: Access inbox:read
inbox:send: Access inbox:send
crm:metadata:read: Access crm:metadata:read
crm:metadata:write: Access crm:metadata:write
inbox:views:read: Access inbox:views:read
inbox:views:write: Access inbox:views:write
meetings:read: Access meetings:read
webhooks:write: Access webhooks:write
````