ConfigHub Attest API

openapi: 3.2.0
info:
  title: Confighub Attest API
  version: 0.1.0
  contact:
    name: ConfigHub Support
    url: https://confighub.com/
    email: hello@confighub.com
  license:
    name: N/A
    url: https://confighub.com/TBD
  termsOfService: TBD
  description: 'Operations tagged Attest across 2 of this provider''s published API definitions: openapi.json, confighub-openapi.json. Each path carries the servers of the definition it was published in.'
servers:
- url: https://hub.confighub.com/api
  description: production
security:
- bearerAuth: []
tags:
- name: Attest
paths:
  /attest:
    post:
      tags:
      - Attest
      summary: Record Attestations across Spaces
      description: Record an Attestation in each Space selected by WhereSpace, SpaceFilterID, ChangeOrderID and TargetStage, covering one Revision of each Unit WhereUnit selects there, named by Revision. When ChangeOrderID is given it defaults to the Revision a Release of the change would bundle, which the ChangeOrder's release Tag marks, or to the one its end Tag marks for a Unit the release Tag does not mark, so the approval satisfies its entry and release gates alike; it defaults to the head Revision otherwise. Each Space is recorded on its own and reported on its own.
      operationId: Attest
      parameters:
      - name: dry_run
        in: query
        description: Resolve the Revisions that would be covered and return the same response without writing anything.
        required: false
        schema:
          type: boolean
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AttestRequest'
      responses:
        default:
          description: Unexpected error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponse'
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttestResult'
        '207':
          description: Recording failed in some Spaces; each Space's result carries its own error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AttestResult'
        '400':
          description: Attest request is invalid (Bad Request).
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponse'
        '401':
          description: Unauthorized access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponse'
        '403':
          description: Forbidden access.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponse'
        '404':
          description: Attest not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponse'
        '409':
          description: Attest data conflict. Data has changed since last read.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponse'
        '500':
          description: Something went wrong while processing Attest.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StandardErrorResponse'
    servers:
    - url: https://hub.confighub.com/api
      description: production
components:
  schemas:
    AttestationSkippedUnit:
      type: object
      properties:
        Message:
          type: string
          description: Why the Unit is not covered, in words.
          x-go-type-skip-optional-pointer: true
        Reason:
          type: string
          description: 'Why the Unit is not covered, as a code: NoTarget or NoRevision.'
          x-go-type-skip-optional-pointer: true
        UnitID:
          type: string
          format: uuid
          example: 248df4b7-aa70-47b8-a036-33ac447e668d
          x-go-type-skip-optional-pointer: true
          x-omitzero: true
        UnitSlug:
          type: string
          x-go-type-skip-optional-pointer: true
    AttestRequest:
      type: object
      properties:
        ChangeOrderID:
          type: string
          format: uuid
          example: 248df4b7-aa70-47b8-a036-33ac447e668d
        Claims:
          type: object
          additionalProperties:
            type: string
          x-go-type-skip-optional-pointer: true
        EvidenceAttestationIDs:
          type: array
          items:
            $ref: '#/components/schemas/UUID'
          x-go-type-skip-optional-pointer: true
        ExpiresAt:
          type: string
          format: date-time
          example: 2006-01-02T15:04:05Z07:00
          x-go-type-skip-optional-pointer: true
          x-omitzero: true
        Note:
          type: string
          x-go-type-skip-optional-pointer: true
        Permissions:
          $ref: '#/components/schemas/Permissions'
        ReleaseID:
          type: string
          format: uuid
          example: 248df4b7-aa70-47b8-a036-33ac447e668d
        Result:
          type: string
          x-go-type-skip-optional-pointer: true
        Revision:
          type: string
          x-go-type-skip-optional-pointer: true
        RevokedAttestationID:
          type: string
          format: uuid
          example: 248df4b7-aa70-47b8-a036-33ac447e668d
        SpaceFilterID:
          type: string
          format: uuid
          example: 248df4b7-aa70-47b8-a036-33ac447e668d
        TargetStage:
          type: string
          x-go-type-skip-optional-pointer: true
        Type:
          type: string
          x-go-type-skip-optional-pointer: true
        WhereSpace:
          type: string
          x-go-type-skip-optional-pointer: true
        WhereUnit:
          type: string
          x-go-type-skip-optional-pointer: true
    ErrorMetadata:
      type: object
      properties:
        EntityID:
          type: string
          description: Optional ID of the entity this error relates to
          x-go-type-skip-optional-pointer: true
        EntitySlug:
          type: string
          description: Optional slug of the entity this error relates to
          x-go-type-skip-optional-pointer: true
        EntityType:
          type: string
          description: Optional type of the entity this error relates to
          x-go-type-skip-optional-pointer: true
        Items:
          type: array
          items:
            $ref: '#/components/schemas/ErrorItem'
          description: Collection of error details
          x-go-type-skip-optional-pointer: true
    AttestSpaceResult:
      type: object
      properties:
        Attestation:
          $ref: '#/components/schemas/Attestation'
        Error:
          $ref: '#/components/schemas/ResponseError'
        SkippedUnits:
          type: array
          items:
            $ref: '#/components/schemas/AttestationSkippedUnit'
          x-go-type-skip-optional-pointer: true
        SpaceID:
          type: string
          format: uuid
          example: 248df4b7-aa70-47b8-a036-33ac447e668d
          x-go-type-skip-optional-pointer: true
          x-omitzero: true
        SpaceSlug:
          type: string
          x-go-type-skip-optional-pointer: true
        Subjects:
          type: array
          items:
            $ref: '#/components/schemas/AttestationSubject'
          x-go-type-skip-optional-pointer: true
    ErrorItem:
      type: object
      properties:
        Description:
          type: string
          description: A clear explanation of what went wrong
          x-go-type-skip-optional-pointer: true
        Item:
          type: string
          description: The name of the field, resource, or entity that the error relates to
          x-go-type-skip-optional-pointer: true
    AttestResult:
      type: object
      properties:
        Spaces:
          type: array
          items:
            $ref: '#/components/schemas/AttestSpaceResult'
          x-go-type-skip-optional-pointer: true
    Subjects:
      type: object
      properties:
        GroupIDs:
          type: object
          additionalProperties:
            type: boolean
          x-go-type-skip-optional-pointer: true
        UserIDs:
          type: object
          additionalProperties:
            type: boolean
          x-go-type-skip-optional-pointer: true
    Attestation:
      type: object
      properties:
        AttestationID:
          type: string
          description: Uniquely identifies the Attestation.
          format: uuid
          example: 248df4b7-aa70-47b8-a036-33ac447e668d
          x-confighub-where:
            dataType: uuid
          x-go-type-skip-optional-pointer: true
          x-omitzero: true
        ChangeOrderID:
          type: string
          description: 'The ChangeOrder the Attestation was made in the context of. Context only: it does not change which Revisions are covered.'
          format: uuid
          example: 248df4b7-aa70-47b8-a036-33ac447e668d
          x-confighub-where:
            dataType: uuid
            references: ChangeOrder
        Claims:
          type: object
          additionalProperties:
            type: string
          description: Anything else the attester records, as string key/value pairs with the limits of Annotations.
          x-confighub-where:
            dataType: map[string]string
          x-go-type-skip-optional-pointer: true
        CreatedAt:
          type: string
          description: The timestamp when the entity was created in "2023-01-01T12:00:00Z" format.
          format: date-time
          readOnly: true
          example: '2025-04-04T11:50:02.95102-07:00'
          x-confighub-where:
            dataType: time
          x-go-type-skip-optional-pointer: true
          x-omitzero: true
        EntityType:
          type: string
          description: The type of entity.
          readOnly: true
          x-go-type-skip-optional-pointer: true
        EvidenceAttestationIDs:
          type: array
          items:
            $ref: '#/components/schemas/UUID'
          description: Other Attestations this one relied on. They may be in other Spaces.
          x-confighub-where:
            dataType: '[]uuid'
            references: Attestation
          x-go-type-skip-optional-pointer: true
        ExpiresAt:
          type: string
          description: When the Attestation stops satisfying requirements. Optional.
          format: date-time
          example: 2006-01-02T15:04:05Z07:00
          x-confighub-where:
            dataType: time
          x-go-type-skip-optional-pointer: true
          x-omitzero: true
        Hash:
          type: string
          description: 'SHA256 hash of the claim encoded as hexadecimal: the statement (Type, Result, RevokedAttestationID, ChangeOrderID, ReleaseID, EvidenceAttestationIDs, Note, Claims and ExpiresAt), the User who recorded it, and the Revisions it covers. (readonly)'
          readOnly: true
          x-confighub-where:
            dataType: string
          x-go-type-skip-optional-pointer: true
        HiddenReason:
          type: string
          description: The reason the entity is hidden, if it is. A hidden entity is left out of List and Search results, and of what bulk operations act on, unless the include_hidden parameter names its reason or is *, or the where parameter names the entity by Slug or ID. ConfigHub/YAML Units are created hidden with the reason BackingUnit unless given another.
          x-confighub-where:
            dataType: string
          x-go-type-skip-optional-pointer: true
        Note:
          type: string
          description: The attester's reason, in their own words.
          x-confighub-where:
            dataType: string
          x-go-type-skip-optional-pointer: true
        OrganizationID:
          type: string
          description: The Organization the Attestation belongs to.
          format: uuid
          example: 248df4b7-aa70-47b8-a036-33ac447e668d
          x-confighub-where:
            dataType: uuid
            references: Organization
            expandable: true
          x-go-type-skip-optional-pointer: true
          x-omitzero: true
        Permissions:
          allOf:
          - $ref: '#/components/schemas/Permissions'
          description: Permissions to access this attestation.
          x-confighub-where:
            dataType: map[string]map[string]map[uuid]bool
        ReleaseID:
          type: string
          description: A published Release the claim is about.
          format: uuid
          example: 248df4b7-aa70-47b8-a036-33ac447e668d
          x-confighub-where:
            dataType: uuid
            references: Release
        Result:
          enum:
          - Pass
          - Fail
          type: string
          description: 'The outcome: Pass or Fail. For an Approval, approve or reject. Defaults to Pass.'
          x-confighub-where:
            dataType: string
          x-go-type-skip-optional-pointer: true
        RevokedAttestationID:
          type: string
          description: An earlier Attestation in the same Space that this one withdraws. A revocation covers no Revisions of its own.
          format: uuid
          example: 248df4b7-aa70-47b8-a036-33ac447e668d
          x-confighub-where:
            dataType: uuid
            references: Attestation
        SpaceID:
          type: string
          description: The Space the Attestation belongs to. Every Revision it covers is in this Space.
          format: uuid
          example: 248df4b7-aa70-47b8-a036-33ac447e668d
          x-confighub-where:
            dataType: uuid
            references: Space
            expandable: true
          x-go-type-skip-optional-pointer: true
          x-omitzero: true
        SpaceSlug:
          type: string
          description: Slug of the Space the Attestation belongs to.
          readOnly: true
          x-go-type-skip-optional-pointer: true
        Type:
          type: string
          description: What is being claimed, such as Approval. Requirements select Attestations by it. Defaults to Approval.
          x-confighub-where:
            dataType: string
          x-go-type-skip-optional-pointer: true
        UpdatedAt:
          type: string
          description: The timestamp when the entity was last updated in "2023-01-01T12:00:00Z" format.
          format: date-time
          readOnly: true
          example: '2025-04-04T11:50:02.95102-07:00'
          x-go-type-skip-optional-pointer: true
          x-omitzero: true
        UserID:
          type: string
          description: The authenticated User that created the Attestation.
          format: uuid
          readOnly: true
          example: 248df4b7-aa70-47b8-a036-33ac447e668d
          x-confighub-where:
            dataType: uuid
            references: User
          x-go-type-skip-optional-pointer: true
          x-omitzero: true
        Version:
          type: integer
          description: An entity-specific sequence number used for optimistic concurrency control. The value read must be sent in calls to Update.
          format: int64
          readOnly: false
          x-go-type-skip-optional-pointer: true
      description: 'An Attestation records that a principal made a claim about specific Revisions, all in its Space: that they approve them, that a review or check passed or failed, or anything else its Type names. It is never updated; withdrawing one is a new Attestation naming it in RevokedAttestationID.'
    ResponseError:
      type: object
      properties:
        Details:
          type: array
          items:
            type: string
          description: Additional context messages
          x-go-type-skip-optional-pointer: true
        ErrorMetadata:
          allOf:
          - $ref: '#/components/schemas/ErrorMetadata'
          description: Structured error details like field violations
        Message:
          type: string
          description: The primary error message
          x-go-type-skip-optional-pointer: true
        Status:
          type: integer
          description: HTTP status code
          x-go-type-skip-optional-pointer: true
        Type:
          type: string
          description: 'The category of the error, as a code: UserInput, Validation, Data, Authentication, Permission, NotFound, Conflict, AlreadyExists, Unprocessable, Locked, PreconditionFailed, TooManyRequests, Unexpected, GatewayTimeout, or ServiceUnavailable'
          x-go-type-skip-optional-pointer: true
    Permissions:
      type: object
      additionalProperties:
        $ref: '#/components/schemas/Subjects'
    AttestationSubject:
      type: object
      properties:
        Authored:
          type: boolean
          description: With a ChangeOrder, the caller wrote one of the Revisions of the change on this Unit in this Space, so the Attestation does not count here for a prerequisite that excludes authors.
          x-go-type-skip-optional-pointer: true
        RevisionID:
          type: string
          format: uuid
          example: 248df4b7-aa70-47b8-a036-33ac447e668d
          x-go-type-skip-optional-pointer: true
          x-omitzero: true
        RevisionNum:
          type: integer
          format: int64
          x-go-type-skip-optional-pointer: true
        UnitID:
          type: string
          format: uuid
          example: 248df4b7-aa70-47b8-a036-33ac447e668d
          x-go-type-skip-optional-pointer: true
          x-omitzero: true
        UnitSlug:
          type: string
          x-go-type-skip-optional-pointer: true
    UUID:
      type: string
      format: uuid
      example: 248df4b7-aa70-47b8-a036-33ac447e668d
    StandardErrorResponse:
      type: object
      properties:
        Error:
          allOf:
          - $ref: '#/components/schemas/ResponseError'
          description: 'The error: its message, category (Type), HTTP status, details, and structured items.'
        message:
          type: string
          description: 'The error as one string: its message, with any details, items, and individual errors appended. Kept for clients written before Error; new clients read Error.'
          x-go-type-skip-optional-pointer: true
      description: 'The body of an error response: the error as data (Error), and as one string (message) for clients written before Error.'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Bearer authentication
x-refined-from:
- openapi.json
- confighub-openapi.json