> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pnbr.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Stage records

> Stage entities and relationships in a workspace.

**Operation ID:** `http.graph.workspaces.capture`

```http theme={null}
POST /v1/orgs/{org}/projects/{project}/graph/workspaces/{ws}/capture
```


## OpenAPI

````yaml openapi.json POST /v1/orgs/{org}/projects/{project}/graph/workspaces/{ws}/capture
openapi: 3.1.0
info:
  title: Penumbra API
  version: v1
  description: >-
    HTTP reference for Files, search, extraction, reviews, Graph, Shapes and
    sharing.
servers:
  - url: https://api.pnbr.io
    description: Penumbra API
security: []
paths:
  /v1/orgs/{org}/projects/{project}/graph/workspaces/{ws}/capture:
    post:
      tags:
        - Review workspaces
      summary: Stage records
      description: |-
        Stage entities and relationships in a workspace.

        Product guidance: [Workspace](/concepts/workspace).
      operationId: http.graph.workspaces.capture
      parameters:
        - name: org
          in: path
          required: true
          schema:
            type: string
        - name: project
          in: path
          required: true
          schema:
            type: string
        - name: ws
          in: path
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/http_graph_workspaces_capture_request'
      responses:
        2XX:
          description: Success.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/http_graph_workspaces_capture_response'
      security:
        - bearerAuth: []
components:
  schemas:
    http_graph_workspaces_capture_request:
      type: object
      properties:
        capture_binding:
          description: >-
            Named capture binding from the exact Shape artifact. Required links
            are checked when the workspace is submitted.
          type: string
          minLength: 1
          maxLength: 128
        expected_artifact:
          description: >-
            Require this exact Shape artifact for every staged item. Set shape
            to its Shape id. A mismatched workspace binding or selected
            published head is refused before items are written.
          type: object
          properties:
            shape_id:
              type: string
              format: uuid
              pattern: >-
                ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
            artifact_digest:
              type: string
              pattern: ^sha256:[0-9a-f]{64}$
          required:
            - shape_id
            - artifact_digest
          additionalProperties: false
        shape:
          description: >-
            Default Shape (name or id) for items in this call that do not name
            their own. Needed only when a type or relationship name is declared
            by several published Shapes.
          type: string
          minLength: 1
          maxLength: 200
        entities:
          maxItems: 100
          type: array
          items:
            type: object
            properties:
              ref:
                description: Short local ref for relationships in this workspace.
                type: string
                pattern: ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$
              type:
                description: Entity type name from a published Shape.
                type: string
                minLength: 1
              name:
                description: >-
                  Omit when the Shape declares a titular property; the server
                  derives it.
                anyOf:
                  - type: string
                    maxLength: 1024
                  - type: 'null'
              description:
                anyOf:
                  - type: string
                    maxLength: 8192
                  - type: 'null'
              properties:
                description: Properties per the Shape's schema for this type.
                type: object
                propertyNames:
                  type: string
                additionalProperties: {}
              shape:
                description: >-
                  Shape (name or id) governing this entity, when its type name
                  is in several Shapes.
                type: string
                minLength: 1
                maxLength: 200
              evidence:
                description: >-
                  Exact File citations for this item. Prefer {citation} with the
                  token read returns for a passage or quote: it carries the
                  quoted text range, so the citation shows exactly what supports
                  the item. The File-id form cites a whole version or an exact
                  range when all four quote fields are present. Verified against
                  Files at staging: the version must exist and carry this
                  digest, and a quoted range must match its text. A citation
                  records what was read; it grants no access and proves no
                  entailment.
                maxItems: 32
                type: array
                items:
                  anyOf:
                    - type: object
                      properties:
                        citation:
                          description: >-
                            The citation token read returned for the passage or
                            quote you are citing, passed unchanged. The server
                            resolves it to the exact File, version, digest and
                            quoted text range and verifies them against Files.
                            Example: citation: 'cite1.AZ8j…'.
                          type: string
                          minLength: 8
                          maxLength: 1024
                        note:
                          type: string
                          minLength: 1
                          maxLength: 500
                      required:
                        - citation
                      additionalProperties: false
                    - type: object
                      properties:
                        kind:
                          type: string
                          const: file
                        file_id:
                          description: Native File id.
                          type: string
                          format: uuid
                          pattern: >-
                            ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        version_id:
                          description: The immutable File version actually read.
                          type: string
                          format: uuid
                          pattern: >-
                            ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        content_digest:
                          description: >-
                            That version's sha256 content digest, as Files
                            reports it.
                          type: string
                          pattern: ^sha256:[0-9a-f]{64}$
                        chunk_id:
                          description: >-
                            Native Files chunk id; must resolve to this exact
                            File and version.
                          type: string
                          format: uuid
                          pattern: >-
                            ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        quote:
                          description: >-
                            Exact parsed-text quote, at most 4096 UTF-8 bytes;
                            provide all four quote fields together.
                          type: string
                          minLength: 1
                          maxLength: 4096
                        start_byte:
                          description: >-
                            Inclusive UTF-8 byte offset in this version's parsed
                            text.
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                        end_byte_exclusive:
                          description: >-
                            Exclusive UTF-8 byte offset in this version's parsed
                            text.
                          type: integer
                          exclusiveMinimum: 0
                          maximum: 9007199254740991
                        quote_digest:
                          description: SHA-256 digest of the exact quote's UTF-8 bytes.
                          type: string
                          pattern: ^sha256:[0-9a-f]{64}$
                        note:
                          type: string
                          minLength: 1
                          maxLength: 500
                      required:
                        - file_id
                        - version_id
                        - content_digest
                      additionalProperties: false
            required:
              - type
        relationships:
          maxItems: 100
          type: array
          items:
            type: object
            properties:
              ref:
                type: string
                pattern: ^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$
              type:
                description: Relationship type (edge type) from a published Shape.
                type: string
                minLength: 1
              from:
                description: >-
                  Source: a ref from this call, a staged ref, a staged handle,
                  or a staged entity's name.
                type: string
                minLength: 1
              to:
                description: Target, resolved the same way.
                type: string
                minLength: 1
              properties:
                description: Properties per the Shape's schema for this type.
                type: object
                propertyNames:
                  type: string
                additionalProperties: {}
              shape:
                description: >-
                  Shape (name or id) declaring this relationship, when several
                  Shapes declare the edge type for these endpoints.
                type: string
                minLength: 1
                maxLength: 200
              bridge:
                description: >-
                  Stable project RelationshipId. Required only when several
                  published project bridges fit the same edge type and endpoint
                  types.
                type: string
                format: uuid
                pattern: >-
                  ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
              evidence:
                description: >-
                  Exact File citations for this item. Prefer {citation} with the
                  token read returns for a passage or quote: it carries the
                  quoted text range, so the citation shows exactly what supports
                  the item. The File-id form cites a whole version or an exact
                  range when all four quote fields are present. Verified against
                  Files at staging: the version must exist and carry this
                  digest, and a quoted range must match its text. A citation
                  records what was read; it grants no access and proves no
                  entailment.
                maxItems: 32
                type: array
                items:
                  anyOf:
                    - type: object
                      properties:
                        citation:
                          description: >-
                            The citation token read returned for the passage or
                            quote you are citing, passed unchanged. The server
                            resolves it to the exact File, version, digest and
                            quoted text range and verifies them against Files.
                            Example: citation: 'cite1.AZ8j…'.
                          type: string
                          minLength: 8
                          maxLength: 1024
                        note:
                          type: string
                          minLength: 1
                          maxLength: 500
                      required:
                        - citation
                      additionalProperties: false
                    - type: object
                      properties:
                        kind:
                          type: string
                          const: file
                        file_id:
                          description: Native File id.
                          type: string
                          format: uuid
                          pattern: >-
                            ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        version_id:
                          description: The immutable File version actually read.
                          type: string
                          format: uuid
                          pattern: >-
                            ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        content_digest:
                          description: >-
                            That version's sha256 content digest, as Files
                            reports it.
                          type: string
                          pattern: ^sha256:[0-9a-f]{64}$
                        chunk_id:
                          description: >-
                            Native Files chunk id; must resolve to this exact
                            File and version.
                          type: string
                          format: uuid
                          pattern: >-
                            ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
                        quote:
                          description: >-
                            Exact parsed-text quote, at most 4096 UTF-8 bytes;
                            provide all four quote fields together.
                          type: string
                          minLength: 1
                          maxLength: 4096
                        start_byte:
                          description: >-
                            Inclusive UTF-8 byte offset in this version's parsed
                            text.
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                        end_byte_exclusive:
                          description: >-
                            Exclusive UTF-8 byte offset in this version's parsed
                            text.
                          type: integer
                          exclusiveMinimum: 0
                          maximum: 9007199254740991
                        quote_digest:
                          description: SHA-256 digest of the exact quote's UTF-8 bytes.
                          type: string
                          pattern: ^sha256:[0-9a-f]{64}$
                        note:
                          type: string
                          minLength: 1
                          maxLength: 500
                      required:
                        - file_id
                        - version_id
                        - content_digest
                      additionalProperties: false
            required:
              - type
              - from
              - to
        idempotency_key:
          description: >-
            Required caller-chosen command identity. Reuse the same key and body
            after a lost reply; choose a fresh key for new intent, even if the
            content is identical. Replay returns the original receipt and never
            recreates edited or removed items.
          type: string
          minLength: 1
          maxLength: 200
      required:
        - idempotency_key
      additionalProperties: false
    http_graph_workspaces_capture_response:
      type: object
      properties:
        data:
          type: object
          properties:
            workspace:
              type: object
              properties:
                id:
                  type: string
                creation_origin:
                  type: string
                name:
                  type: string
                description:
                  anyOf:
                    - type: string
                    - type: 'null'
                status:
                  type: string
                  enum:
                    - open
                    - submitted
                    - applied
                    - closed
                revision:
                  type: integer
                  minimum: -9007199254740991
                  maximum: 9007199254740991
                item_count:
                  type: integer
                  minimum: -9007199254740991
                  maximum: 9007199254740991
                shape:
                  anyOf:
                    - type: object
                      properties:
                        shape_id:
                          type: string
                        artifact_digest:
                          type: string
                      required:
                        - shape_id
                        - artifact_digest
                      additionalProperties: {}
                    - type: 'null'
                bindings:
                  type: array
                  items:
                    type: object
                    properties:
                      shape_id:
                        type: string
                      artifact_digest:
                        type: string
                    required:
                      - shape_id
                      - artifact_digest
                    additionalProperties: {}
                bridge_set:
                  anyOf:
                    - type: object
                      properties:
                        digest:
                          type: string
                        declaration_count:
                          type: integer
                          minimum: -9007199254740991
                          maximum: 9007199254740991
                      required:
                        - digest
                        - declaration_count
                      additionalProperties: {}
                    - type: 'null'
                created_at:
                  type: string
                updated_at:
                  type: string
                applied_at:
                  anyOf:
                    - type: string
                    - type: 'null'
                replaced_by:
                  type: string
              required:
                - id
                - creation_origin
                - name
                - description
                - status
                - revision
                - item_count
                - shape
                - bindings
                - bridge_set
                - created_at
                - updated_at
                - applied_at
              additionalProperties: {}
            staged:
              type: array
              items:
                oneOf:
                  - type: object
                    properties:
                      kind:
                        type: string
                        const: entity
                      handle:
                        type: string
                      ref:
                        anyOf:
                          - type: string
                          - type: 'null'
                      type_name:
                        type: string
                      name:
                        type: string
                      properties:
                        type: object
                        propertyNames:
                          type: string
                        additionalProperties: {}
                      binding:
                        type: object
                        properties:
                          shape_id:
                            type: string
                          artifact_digest:
                            type: string
                        required:
                          - shape_id
                          - artifact_digest
                        additionalProperties: {}
                      evidence:
                        type: array
                        items:
                          type: object
                          properties: {}
                          additionalProperties: {}
                      created_at:
                        type: string
                    required:
                      - kind
                      - handle
                      - ref
                      - type_name
                      - name
                      - properties
                      - binding
                      - evidence
                      - created_at
                    additionalProperties: {}
                  - type: object
                    properties:
                      kind:
                        type: string
                        const: relationship
                      handle:
                        type: string
                      ref:
                        anyOf:
                          - type: string
                          - type: 'null'
                      edge_type:
                        type: string
                      source:
                        type: object
                        properties: {}
                        additionalProperties: {}
                      target:
                        type: object
                        properties: {}
                        additionalProperties: {}
                      properties:
                        type: object
                        propertyNames:
                          type: string
                        additionalProperties: {}
                      evidence:
                        type: array
                        items:
                          type: object
                          properties: {}
                          additionalProperties: {}
                      created_at:
                        type: string
                    required:
                      - kind
                      - handle
                      - ref
                      - edge_type
                      - source
                      - target
                      - properties
                      - evidence
                      - created_at
                    additionalProperties: {}
                  - type: object
                    properties:
                      kind:
                        type: string
                        const: hydrated_node
                      handle:
                        type: string
                      node_id:
                        type: string
                      witness_revision:
                        type: integer
                        minimum: -9007199254740991
                        maximum: 9007199254740991
                      intent:
                        type: string
                        enum:
                          - update
                          - delete
                      snapshot:
                        type: object
                        properties: {}
                        additionalProperties: {}
                      evidence:
                        type: array
                        items:
                          type: object
                          properties: {}
                          additionalProperties: {}
                      created_at:
                        type: string
                    required:
                      - kind
                      - handle
                      - node_id
                      - witness_revision
                      - intent
                      - snapshot
                      - evidence
                      - created_at
                    additionalProperties: {}
                  - type: object
                    properties:
                      kind:
                        type: string
                        const: hydrated_edge
                      handle:
                        type: string
                      edge_id:
                        type: string
                      witness_revision:
                        type: integer
                        minimum: -9007199254740991
                        maximum: 9007199254740991
                      intent:
                        type: string
                        enum:
                          - update
                          - delete
                      snapshot:
                        type: object
                        properties: {}
                        additionalProperties: {}
                      evidence:
                        type: array
                        items:
                          type: object
                          properties: {}
                          additionalProperties: {}
                      created_at:
                        type: string
                    required:
                      - kind
                      - handle
                      - edge_id
                      - witness_revision
                      - intent
                      - snapshot
                      - evidence
                      - created_at
                    additionalProperties: {}
            notes:
              type: array
              items:
                type: string
            replayed:
              type: boolean
            bindings:
              type: array
              items:
                type: object
                properties:
                  shape_id:
                    type: string
                  artifact_digest:
                    type: string
                required:
                  - shape_id
                  - artifact_digest
                additionalProperties: {}
          required:
            - workspace
            - staged
            - notes
            - replayed
            - bindings
          additionalProperties: {}
      required:
        - data
      additionalProperties: false
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.