> ## Documentation Index > Fetch the complete documentation index at: https://docs.item.app/llms.txt > Use this file to discover all available pages before exploring further. # List objects or fetch by ID > **List mode** (no `id` or `email` param): Returns a paginated list of objects with optional search, filtering, and sorting. **Single-object mode** (with `id` or `email`): Returns a single object by ID or email lookup. ## OpenAPI ````yaml /openapi.yaml get /api/objects/{objectType} openapi: 3.1.0 info: title: item API description: > The item API provides full CRUD access to your organization's data — People, Companies, and Custom Objects. Use it to: - Push structured data into item on a schedule - Sync custom field values across your stack - Pull filtered records and pre-configured views - Use item as your source of truth for customer data ## Authentication All requests require an API key passed in the `x-api-key` header. You can generate an API key from **Settings > System > API Key** in your item workspace. ```bash curl -H "x-api-key: sk_live_..." https://app.useitem.io/api/objects/contacts ``` version: 1.0.0 contact: name: item Support servers: - url: https://app.useitem.io description: Production - url: http://localhost:3000 description: Local development security: - apiKey: [] tags: - name: Objects description: Create, read, update, and delete People, Companies, and Custom Objects. - name: Schema description: Discover available object types and their field definitions. - name: Users description: List organization members and their access levels. - name: Views description: List and execute pre-configured views to pull filtered data. - name: Batch description: Bulk create or update objects for high-frequency sync operations. - name: Webhooks description: Trigger skills (AI agents) via HTTP webhooks from external systems. paths: /api/objects/{objectType}: parameters: - $ref: '#/components/parameters/objectType' get: tags: - Objects summary: List objects or fetch by ID description: > **List mode** (no `id` or `email` param): Returns a paginated list of objects with optional search, filtering, and sorting. **Single-object mode** (with `id` or `email`): Returns a single object by ID or email lookup. operationId: listOrGetObjects parameters: - name: id in: query description: >- Fetch a single object by ID. When provided, returns one object instead of a list. schema: type: integer example: 123 - name: email in: query description: >- Fetch a contact by email (contacts only). When provided, returns one object. schema: type: string example: alex@acme.com - name: limit in: query description: 'Maximum records to return (list mode only). Default: 50, max: 200.' schema: type: integer default: 50 maximum: 200 - name: offset in: query description: Number of records to skip for pagination (list mode only). schema: type: integer default: 0 - name: search in: query description: Text search on `name` (and `email` for contacts). schema: type: string example: acme - name: sort_by in: query description: 'Field to sort by. Default: `created_at`.' schema: type: string default: created_at example: name - name: sort_order in: query description: 'Sort direction. Default: `desc`.' schema: type: string enum: - asc - desc default: desc - name: filter[{field_name}] in: query description: > Filter by field value (case-insensitive partial match). Works with both system fields and custom fields. Example: `filter[industry]=Technology` schema: type: string - name: include_all_fields in: query description: Include all system fields in the response (single-object mode only). schema: type: boolean default: false - name: include_summary in: query description: >- Include the AI-generated summary (contacts and companies only, single-object mode). schema: type: boolean default: false responses: '200': description: Success content: application/json: schema: oneOf: - title: List response type: object properties: data: type: array items: $ref: '#/components/schemas/ObjectRecord' pagination: $ref: '#/components/schemas/Pagination' - title: Single object response type: object properties: data: $ref: '#/components/schemas/ObjectRecord' '400': description: Bad request content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Invalid or missing API key content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Object type or record not found content: application/json: schema: $ref: '#/components/schemas/Error' components: parameters: objectType: name: objectType in: path required: true description: > The object type slug. Use `contacts` for People, `companies` for Companies, or the slug of a Custom Object (e.g., `deals`, `tickets`). Singular forms (`contact`, `company`) are also accepted. schema: type: string examples: contacts: value: contacts summary: People companies: value: companies summary: Companies custom: value: deals summary: Custom object schemas: ObjectRecord: type: object description: > A flat object containing all fields. System fields (name, email, phone, etc.) and custom fields are merged into a single level — the `custom_fields` JSON column is flattened so every field is a top-level key. properties: id: type: integer description: Unique record ID example: 123 name: type: string example: Alex Johnson email: type: string example: alex@acme.com created_at: type: string format: date-time updated_at: type: string format: date-time additionalProperties: true Pagination: type: object properties: total: type: integer description: Total number of records matching the query example: 150 limit: type: integer description: Maximum records returned per page example: 50 offset: type: integer description: Number of records skipped example: 0 has_more: type: boolean description: Whether more records exist beyond this page example: true Error: type: object properties: error: type: string example: Object not found securitySchemes: apiKey: type: apiKey in: header name: x-api-key description: Your organization's API key (starts with `sk_live_`) ````