> ## Documentation Index > Fetch the complete documentation index at: https://docs.gumnut.ai/llms.txt > Use this file to discover all available pages before exploring further. # List bodies > Returns a paginated list of bodies, newest first, optionally filtered by asset, person, or ID. A body is a person in a photo without a face record, for example someone facing away from the camera. Its `person_id` is `null` until it is linked; link it with `update_body`. **Use `list_faces` instead** for face detections, and `list_people` for the people themselves. To choose photos of a person, use `list_assets` or `search_assets` with `person_ids`. A body match may not show their face, so when choosing photos of someone, prefer `person_link=face`. **Pagination** is cursor-based: when `has_more` is true, pass the `id` of the last body in `data` as `starting_after_id` to fetch the next page. ## OpenAPI ````yaml https://api.gumnut.ai/openapi.json get /api/bodies openapi: 3.1.0 info: title: Gumnut API description: >- The Gumnut API manages photo and video libraries: upload and organize assets, search by content, group detected faces into people, and curate albums and stacks. Headless clients authenticate by sending either a Gumnut API key (`apikey_...`) or an OAuth access token as a Bearer token in the `Authorization` header. The Gumnut web and mobile apps sign in with a first-party session (Clerk session JWT) instead, which is also the only credential that can manage API keys and library sharing. contact: name: Gumnut url: https://www.gumnut.ai/contact version: 1.0.0 servers: - url: https://api.gumnut.ai description: Production security: - apiKeyAuth: [] - oauthJwtAuth: [] tags: - name: assets description: >- Photos and videos in a library: upload, list and filter, update metadata, trash and restore. - name: search description: >- Content-based search over a library's assets, with album, person, date, and location filters. - name: albums description: User-curated collections of assets. - name: album-assets description: Link records connecting albums to their member assets. - name: stacks description: >- Groups of related shots of the same moment, presented as a single unit with a cover asset. - name: people description: Named people, each built from clustered faces. - name: faces description: Detected faces and their assignment to people. - name: bodies description: People found in photos without a face record. - name: libraries description: Top-level containers that own assets, albums, people, and everything else. - name: library-invitations description: First-party invitation management and admission for photo libraries. - name: events description: Change-event feed for keeping client state in sync. - name: tasks description: Status of background processing tasks. - name: users description: The authenticated user's profile. - name: api-keys description: >- Create and manage Gumnut API keys. Requires a first-party Gumnut app session — API keys and OAuth tokens cannot manage credentials. - name: oauth description: OAuth flow endpoints for obtaining and refreshing access tokens. - name: feedback description: Reports of friction using Gumnut. - name: server description: Service health. paths: /api/bodies: get: tags: - bodies summary: List bodies description: >- Returns a paginated list of bodies, newest first, optionally filtered by asset, person, or ID. A body is a person in a photo without a face record, for example someone facing away from the camera. Its `person_id` is `null` until it is linked; link it with `update_body`. **Use `list_faces` instead** for face detections, and `list_people` for the people themselves. To choose photos of a person, use `list_assets` or `search_assets` with `person_ids`. A body match may not show their face, so when choosing photos of someone, prefer `person_link=face`. **Pagination** is cursor-based: when `has_more` is true, pass the `id` of the last body in `data` as `starting_after_id` to fetch the next page. operationId: list_bodies parameters: - name: asset_id in: query required: false schema: anyOf: - type: string - type: 'null' description: Return only bodies in this asset. title: Asset Id description: Return only bodies in this asset. - name: person_id in: query required: false schema: anyOf: - type: string - type: 'null' description: Return only bodies linked to this person. title: Person Id description: Return only bodies linked to this person. - name: ids in: query required: false schema: anyOf: - items: type: string type: array - type: 'null' description: >- Look up specific bodies by ID (max 200). IDs use the `body_` prefix. Accepts multiple `ids=` query params or a single comma-delimited value (e.g., `ids=body_1,body_2`). title: Ids description: >- Look up specific bodies by ID (max 200). IDs use the `body_` prefix. Accepts multiple `ids=` query params or a single comma-delimited value (e.g., `ids=body_1,body_2`). - name: limit in: query required: false schema: type: integer maximum: 200 minimum: 1 description: Maximum number of bodies per page (1–200). Defaults to 20. default: 20 title: Limit description: Maximum number of bodies per page (1–200). Defaults to 20. - name: starting_after_id in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Cursor for pagination. Pass the `id` of the last body in the previous response's `data` to fetch the next page. Omit for the first page. title: Starting After Id description: >- Cursor for pagination. Pass the `id` of the last body in the previous response's `data` to fetch the next page. Omit for the first page. - name: library_id in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Library to list from. Optional if the user has a single live (non-trashed) library; required when they have multiple. title: Library Id description: >- Library to list from. Optional if the user has a single live (non-trashed) library; required when they have multiple. responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/PaginatedBodiesResponse' '401': description: Missing, invalid, or expired credentials. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '403': description: >- The credentials are valid but not authorized for this operation — for example an API key whose action or library scope excludes it, or a credential type this operation does not accept. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '409': description: >- Clerk sign-in could not be associated with the existing account. Resolve the identity conflict before retrying sign-in; repeated requests with unchanged verification and identity state will not resolve it. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/UnprocessableEntityResponse' '429': description: >- Rate limit exceeded, or too many of your requests are already in progress. Retry after the interval in the `Retry-After` header. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '503': description: >- Authentication provider temporarily unavailable. Retry sign-in later. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: PaginatedBodiesResponse: properties: data: items: $ref: '#/components/schemas/BodyResponse' type: array title: Data description: List of bodies has_more: type: boolean title: Has More description: >- True if there are more bodies after this page. Pass the last body's `id` as `starting_after_id` to fetch the next page. type: object required: - data - has_more title: PaginatedBodiesResponse ErrorResponse: title: ErrorResponse type: object properties: detail: title: Detail type: string description: Human-readable explanation of the error. required: - detail UnprocessableEntityResponse: title: UnprocessableEntityResponse type: object properties: detail: title: Detail description: >- A semantic validation message or structured request-validation errors. oneOf: - type: string description: Human-readable semantic validation message. - type: array items: $ref: '#/components/schemas/ValidationError' description: Structured request-validation errors. required: - detail BodyResponse: properties: id: type: string title: Id description: Unique body identifier with 'body_' prefix asset_id: type: string title: Asset Id description: ID of the asset containing this body person_id: anyOf: - type: string - type: 'null' title: Person Id description: >- ID of the person this body is linked to, or `null` when it has none yet. assignment_source: anyOf: - $ref: '#/components/schemas/BodyAssignmentSource' - type: 'null' description: >- 'automatic' when Gumnut linked the person, 'manual' when someone with edit access to the library did. `null` when `person_id` is `null`. bounding_box: additionalProperties: type: integer type: object title: Bounding Box description: >- Where the person is, as {x, y, w, h} in pixels: (x, y) is the box's top-left corner and w, h its size, on the image as displayed (EXIF orientation applied), so they match the asset's `width` and `height` created_at: type: string format: date-time title: Created At description: When this body was detected updated_at: type: string format: date-time title: Updated At description: When this body record was last updated type: object required: - id - asset_id - person_id - assignment_source - bounding_box - created_at - updated_at title: BodyResponse description: A person found in an asset without a face record. ValidationError: properties: loc: items: anyOf: - type: string - type: integer type: array title: Location msg: type: string title: Message type: type: string title: Error Type input: title: Input ctx: type: object title: Context type: object required: - loc - msg - type title: ValidationError BodyAssignmentSource: type: string enum: - automatic - manual title: BodyAssignmentSource description: 'How a body''s person was set: by automatic naming or by a person.' securitySchemes: apiKeyAuth: type: http scheme: bearer description: >- Gumnut API key (`apikey_...`) sent as a Bearer token in the `Authorization` header. Create and manage keys in the Gumnut app, or with the API key endpoints while signed in to it. oauthJwtAuth: type: http scheme: bearer bearerFormat: JWT description: >- Short-lived JWT obtained from the OAuth token exchange, sent as a Bearer token in the `Authorization` header. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.