swagger: '2.0'
info:
  title: Fulcio CA entries API
  version: 2.0.0
  contact:
    name: sigstore Fulcio project
    url: https://github.com/sigstore/fulcio
    email: sigstore-dev@googlegroups.com
  license:
    name: Apache License 2.0
    url: https://github.com/sigstore/fulcio/blob/main/LICENSE
host: fulcio.sigstore.dev
schemes:
- http
consumes:
- application/json
produces:
- application/json
tags:
- name: entries
paths:
  /api/v1/log/entries:
    post:
      summary: Creates an entry in the transparency log
      description: 'Creates an entry in the transparency log for a detached signature, public key, and content.

        '
      operationId: createLogEntry
      tags:
      - entries
      parameters:
      - in: body
        name: proposedEntry
        schema:
          $ref: '#/definitions/ProposedEntry'
        required: true
      responses:
        201:
          description: Returns the entry created in the transparency log
          headers:
            ETag:
              type: string
              description: UUID of log entry
            Location:
              type: string
              description: URI location of log entry
              format: uri
          schema:
            $ref: '#/definitions/LogEntry'
        400:
          $ref: '#/responses/BadContent'
        409:
          $ref: '#/responses/Conflict'
        default:
          $ref: '#/responses/InternalServerError'
    get:
      summary: Retrieves an entry and inclusion proof from the transparency log (if it exists) by index
      operationId: getLogEntryByIndex
      tags:
      - entries
      parameters:
      - in: query
        name: logIndex
        type: integer
        required: true
        minimum: 0
        description: specifies the index of the entry in the transparency log to be retrieved
      responses:
        200:
          description: the entry in the transparency log requested along with an inclusion proof
          schema:
            $ref: '#/definitions/LogEntry'
        404:
          $ref: '#/responses/NotFound'
        default:
          $ref: '#/responses/InternalServerError'
  /api/v1/log/entries/{entryUUID}:
    get:
      summary: Get log entry and information required to generate an inclusion proof for the entry in the transparency log
      description: Returns the entry, root hash, tree size, and a list of hashes that can be used to calculate proof of an entry being included in the transparency log
      operationId: getLogEntryByUUID
      tags:
      - entries
      parameters:
      - in: path
        name: entryUUID
        type: string
        required: true
        pattern: ^([0-9a-fA-F]{64}|[0-9a-fA-F]{80})$
        description: the UUID of the entry for which the inclusion proof information should be returned
      responses:
        200:
          description: Information needed for a client to compute the inclusion proof
          schema:
            $ref: '#/definitions/LogEntry'
        404:
          $ref: '#/responses/NotFound'
        default:
          $ref: '#/responses/InternalServerError'
  /api/v1/log/entries/retrieve:
    post:
      summary: Searches transparency log for one or more log entries
      operationId: searchLogQuery
      tags:
      - entries
      parameters:
      - in: body
        name: entry
        required: true
        schema:
          $ref: '#/definitions/SearchLogQuery'
      responses:
        200:
          description: Returns zero or more entries from the transparency log, according to how many were included in request query
          schema:
            type: array
            items:
              $ref: '#/definitions/LogEntry'
        400:
          $ref: '#/responses/BadContent'
        422:
          $ref: '#/responses/UnprocessableEntity'
        default:
          $ref: '#/responses/InternalServerError'
definitions:
  Error:
    type: object
    properties:
      code:
        type: integer
      message:
        type: string
  LogEntry:
    type: object
    additionalProperties:
      type: object
      properties:
        logID:
          type: string
          pattern: ^[0-9a-fA-F]{64}$
          description: This is the SHA256 hash of the DER-encoded public key for the log at the time the entry was included in the log
        logIndex:
          type: integer
          minimum: 0
        body:
          type: object
          additionalProperties: true
        integratedTime:
          type: integer
          description: The time the entry was added to the log as a Unix timestamp in seconds
        attestation:
          type: object
          properties:
            data:
              format: byte
          format: byte
        verification:
          type: object
          properties:
            inclusionProof:
              $ref: '#/definitions/InclusionProof'
            signedEntryTimestamp:
              type: string
              format: byte
              description: Signature over the logID, logIndex, body and integratedTime.
      required:
      - logID
      - logIndex
      - body
      - integratedTime
  InclusionProof:
    type: object
    properties:
      logIndex:
        type: integer
        description: The index of the entry in the transparency log
        minimum: 0
      rootHash:
        description: The hash value stored at the root of the merkle tree at the time the proof was generated
        type: string
        pattern: ^[0-9a-fA-F]{64}$
      treeSize:
        type: integer
        description: The size of the merkle tree at the time the inclusion proof was generated
        minimum: 1
      hashes:
        description: A list of hashes required to compute the inclusion proof, sorted in order from leaf to root
        type: array
        items:
          type: string
          description: SHA256 hash value expressed in hexadecimal format
          pattern: ^[0-9a-fA-F]{64}$
      checkpoint:
        type: string
        format: signedCheckpoint
        description: The checkpoint (signed tree head) that the inclusion proof is based on
    required:
    - logIndex
    - rootHash
    - treeSize
    - hashes
    - checkpoint
  ProposedEntry:
    type: object
    discriminator: kind
    properties:
      kind:
        type: string
    required:
    - kind
  SearchLogQuery:
    type: object
    properties:
      entryUUIDs:
        type: array
        minItems: 1
        maxItems: 10
        items:
          type: string
          pattern: ^([0-9a-fA-F]{64}|[0-9a-fA-F]{80})$
      logIndexes:
        type: array
        minItems: 1
        maxItems: 10
        items:
          type: integer
          minimum: 0
      entries:
        type: array
        minItems: 1
        maxItems: 10
        items:
          $ref: '#/definitions/ProposedEntry'
responses:
  InternalServerError:
    description: There was an internal error in the server while processing the request
    schema:
      $ref: '#/definitions/Error'
  BadContent:
    description: The content supplied to the server was invalid
    schema:
      $ref: '#/definitions/Error'
  UnprocessableEntity:
    description: The server understood the request but is unable to process the contained instructions
    schema:
      $ref: '#/definitions/Error'
  NotFound:
    description: The content requested could not be found
  Conflict:
    description: The request conflicts with the current state of the transparency log
    schema:
      $ref: '#/definitions/Error'
    headers:
      Location:
        type: string
        format: uri
externalDocs:
  description: More about Fulcio
  url: https://github.com/sigstore/fulcio