api-spec.yaml

paths:
  /operations:
    get:
      summary: Get list of long running operations
      parameters:
      - in: query
        name: type
        schema:
          type: string
        required: false
        description: filter list of long running operations by type
      responses:
        '200':
          content:
            application/json:
              schema:
                type: array
  /oobis:
    post:
      summary: Resolve OOBI and assign an alias for the remote identifier
      description: Resolve OOBI URL or `rpy` message by process results of request
        and assign 'alias' in contact data for resolved identifier
      tags:
      - OOBIs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              description: OOBI
              properties:
                oobialias:
                  type: string
                  description: alias to assign to the identifier resolved from this
                    OOBI
                  required: false
                url:
                  type: string
                  description: URL OOBI
                rpy:
                  type: object
                  description: unsigned KERI `rpy` event message with endpoints
      responses:
        '202':
          description: OOBI resolution to key state successful
  /states:
    get:
      summary: Display key event log (KEL) for given identifier prefix
      description: If provided qb64 identifier prefix is in Kevers, return the current
        state of the identifier along with the KEL and all associated signatures and
        receipts
      tags:
      - Key Event Log
      parameters:
      - in: path
        name: prefix
        schema:
          type: string
        required: true
        description: qb64 identifier prefix of KEL to load
      responses:
        '200':
          description: Key event log and key state of identifier
        '404':
          description: Identifier not found in Key event database
  /events:
    get:
      summary: Display key event log (KEL) for given identifier prefix
      description: If provided qb64 identifier prefix is in Kevers, return the current
        state of the identifier along with the KEL and all associated signatures and
        receipts
      tags:
      - Key Event Log
      parameters:
      - in: path
        name: prefix
        schema:
          type: string
        required: true
        description: qb64 identifier prefix of KEL to load
      responses:
        '200':
          description: Key event log and key state of identifier
        '404':
          description: Identifier not found in Key event database
  /queries:
    post:
      summary: Display key event log (KEL) for given identifier prefix
      description: If provided qb64 identifier prefix is in Kevers, return the current
        state of the identifier along with the KEL and all associated signatures and
        receipts
      tags:
      - Query
      parameters:
      - in: body
        name: pre
        schema:
          type: string
        required: true
        description: qb64 identifier prefix of KEL to load
      responses:
        '200':
          description: Key event log and key state of identifier
        '404':
          description: Identifier not found in Key event database
  /identifiers:
    get: {}
    options: {}
    post: {}
  /challenges:
    get:
      summary: Get random list of words for a 2 factor auth challenge
      description: Get the list of identifiers associated with this agent
      tags:
      - Challenge/Response
      parameters:
      - in: query
        name: strength
        schema:
          type: int
        description: cryptographic strength of word list
        required: false
      responses:
        '200':
          description: An array of random words
          content:
            application/json:
              schema:
                description: Random word list
                type: object
                properties:
                  words:
                    type: array
                    description: random challenge word list
                    items:
                      type: string
  /contacts:
    get:
      summary: Get list of contact information associated with remote identifiers
      description: Get list of contact information associated with remote identifiers.  All
        information is metadata and kept in local storage only
      tags:
      - Contacts
      parameters:
      - in: query
        name: group
        schema:
          type: string
        required: false
        description: field name to group results by
      - in: query
        name: filter_field
        schema:
          type: string
        description: field name to search
        required: false
      - in: query
        name: filter_value
        schema:
          type: string
        description: value to search for
        required: false
      responses:
        '200':
          description: List of contact information for remote identifiers
  /schema:
    get:
      summary: Get schema JSON of all schema
      description: Get schema JSON of all schema
      tags:
      - Schema
      responses:
        '200':
          description: Array of all schema JSON
  /notifications:
    get:
      summary: Get list of notifications for the controller of the agent
      description: Get list of notifications for the controller of the agent.  Notifications
        will be sorted by creation date/time
      parameters:
      - in: header
        name: Range
        schema:
          type: string
        required: false
        description: size of the result list.  Defaults to 25
      tags:
      - Notifications
      responses:
        '200':
          description: List of contact information for remote identifiers
  /operations/{name}:
    delete: {}
    get: {}
  /oobis/{alias}:
    get:
      summary: Get OOBI for specific identifier
      description: Generate OOBI for the identifier of the specified alias and role
      tags:
      - OOBIs
      parameters:
      - in: path
        name: alias
        schema:
          type: string
        required: true
        description: human readable alias for the identifier generate OOBI for
      - in: query
        name: role
        schema:
          type: string
        required: true
        description: role for which to generate OOBI
      responses:
        '200':
          description: An array of Identifier key state information
          content:
            application/json:
              schema:
                description: Key state information for current identifiers
                type: object
  /agent/{caid}:
    get: {}
    put: {}
  /identifiers/{name}:
    get: {}
    put: {}
  /endroles/{aid}:
    get: {}
    post: {}
  /escrows/rpy:
    get: {}
  /challenges/{name}:
    post:
      summary: Sign challenge message and forward to peer identifier
      description: Sign a challenge word list received out of bands and send `exn`
        peer to peer message to recipient
      tags:
      - Challenge/Response
      parameters:
      - in: path
        name: name
        schema:
          type: string
        required: true
        description: Human readable alias for the identifier to create
      requestBody:
        required: true
        content:
          application/json:
            schema:
              description: Challenge response
              properties:
                recipient:
                  type: string
                  description: human readable alias recipient identifier to send signed
                    challenge to
                words:
                  type: array
                  description: challenge in form of word list
                  items:
                    type: string
      responses:
        '202':
          description: Success submission of signed challenge/response
  /contacts/{prefix}:
    delete:
      summary: Delete contact information associated with remote identifier
      description: Delete contact information associated with remote identifier
      tags:
      - Contacts
      parameters:
      - in: path
        name: prefix
        schema:
          type: string
        required: true
        description: qb64 identifier prefix of contact to delete
      responses:
        '202':
          description: Contact information successfully deleted for prefix
        '404':
          description: No contact information found for prefix
    get:
      summary: Get contact information associated with single remote identifier
      description: Get contact information associated with single remote identifier.  All
        information is meta-data and kept in local storage only
      tags:
      - Contacts
      parameters:
      - in: path
        name: prefix
        schema:
          type: string
        required: true
        description: qb64 identifier prefix of contact to get
      responses:
        '200':
          description: Contact information successfully retrieved for prefix
        '404':
          description: No contact information found for prefix
    post:
      summary: Create new contact information for an identifier
      description: Creates new information for an identifier, overwriting all existing
        information for that identifier
      tags:
      - Contacts
      parameters:
      - in: path
        name: prefix
        schema:
          type: string
        required: true
        description: qb64 identifier prefix to add contact metadata to
      requestBody:
        required: true
        content:
          application/json:
            schema:
              description: Contact information
              type: object
      responses:
        '200':
          description: Updated contact information for remote identifier
        '400':
          description: Invalid identifier used to update contact information
        '404':
          description: Prefix not found in identifier contact information
    put:
      summary: Update provided fields in contact information associated with remote
        identifier prefix
      description: Update provided fields in contact information associated with remote
        identifier prefix.  All information is metadata and kept in local storage
        only
      tags:
      - Contacts
      parameters:
      - in: path
        name: prefix
        schema:
          type: string
        required: true
        description: qb64 identifier prefix to add contact metadata to
      requestBody:
        required: true
        content:
          application/json:
            schema:
              description: Contact information
              type: object
      responses:
        '200':
          description: Updated contact information for remote identifier
        '400':
          description: Invalid identifier used to update contact information
        '404':
          description: Prefix not found in identifier contact information
  /schema/{said}:
    get:
      summary: Get schema JSON of specified schema
      description: Get schema JSON of specified schema
      tags:
      - Schema
      parameters:
      - in: path
        name: said
        schema:
          type: string
        required: true
        description: qb64 self-addressing identifier of schema to get
      responses:
        '200':
          description: Schema JSON successfully returned
        '404':
          description: No schema found for SAID
  /credentials/query:
    post:
      summary: List credentials in credential store (wallet)
      description: List issued or received credentials current verified
      tags:
      - Credentials
      parameters:
      - in: path
        name: aid
        schema:
          type: string
        required: true
        description: identifier to load credentials for
      - in: query
        name: type
        schema:
          type: string
        description: type of credential to return, [issued|received]
        required: true
      - in: query
        name: schema
        schema:
          type: string
        description: schema to filter by if provided
        required: false
      responses:
        '200':
          description: Credential list.
          content:
            application/json:
              schema:
                description: Credentials
                type: array
                items:
                  type: object
  /notifications/{said}:
    delete:
      summary: Delete notification
      description: Delete notification
      tags:
      - Notifications
      parameters:
      - in: path
        name: said
        schema:
          type: string
        required: true
        description: qb64 said of note to delete
      responses:
        '202':
          description: Notification successfully deleted for prefix
        '404':
          description: No notification information found for prefix
    put:
      summary: Mark notification as read
      description: Mark notification as read
      tags:
      - Notifications
      parameters:
      - in: path
        name: said
        schema:
          type: string
        required: true
        description: qb64 said of note to mark as read
      responses:
        '202':
          description: Notification successfully marked as read for prefix
        '404':
          description: No notification information found for SAID
  /exchanges/query:
    post: {}
  /exchanges/{said}:
    get: {}
  /identifiers/{name}/oobis:
    get: {}
  /identifiers/{name}/endroles:
    get: {}
    post: {}
  /identifiers/{name}/members:
    get: {}
  /identifiers/{name}/registries:
    get:
      summary: List credential issuance and revocation registies
      description: List credential issuance and revocation registies
      tags:
      - Registries
      responses:
        '200':
          description: array of current credential issuance and revocation registies
    post:
      summary: Request to create a credential issuance and revocation registry
      description: Request to create a credential issuance and revocation registry
      tags:
      - Registries
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name:
                  type: string
                  description: name of the new registry
                alias:
                  type: string
                  description: name of identifier to associate as the issuer of the
                    new credential registry
                toad:
                  type: integer
                  description: Backer receipt threshold
                nonce:
                  type: string
                  description: qb64 encoded ed25519 random seed for registry
                noBackers:
                  type: boolean
                  required: false
                  description: True means to not allow seperate backers from identifier's
                    witnesses.
                baks:
                  type: array
                  items:
                    type: string
                  description: List of qb64 AIDs of witnesses to be used for the new
                    group identifier.
                estOnly:
                  type: boolean
                  required: false
                  default: false
                  description: True means to not allow interaction events to anchor
                    credential events.
      responses:
        '202':
          description: registry inception request has been submitted
  /identifiers/{name}/credentials:
    post:
      summary: Perform credential issuance
      description: Perform credential issuance
      tags:
      - Credentials
      parameters:
      - in: path
        name: alias
        schema:
          type: string
        required: true
        description: Human readable alias for the identifier to create
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                registry:
                  type: string
                  description: Alias of credential issuance/revocation registry (aka
                    status)
                recipient:
                  type: string
                  description: AID of credential issuance/revocation recipient
                schema:
                  type: string
                  description: SAID of credential schema being issued
                rules:
                  type: object
                  description: Rules section (Ricardian contract) for credential being
                    issued
                source:
                  type: object
                  description: ACDC edge or edge group for chained credentials
                  properties:
                    d:
                      type: string
                      description: SAID of reference chain
                    s:
                      type: string
                      description: SAID of reference chain schema
                credentialData:
                  type: object
                  description: dynamic map of values specific to the schema
                private:
                  type: boolean
                  description: flag to inidicate this credential should support privacy
                    preserving presentations
      responses:
        '200':
          description: Credential issued.
          content:
            application/json:
              schema:
                description: Credential
                type: object
  /identifiers/{name}/exchanges:
    post: {}
  /endroles/{aid}/{role}:
    get: {}
    post: {}
  /contacts/{prefix}/img:
    get:
      summary: Get contact image for identifer prefix
      description: Get contact image for identifer prefix
      tags:
      - Contacts
      parameters:
      - in: path
        name: prefix
        schema:
          type: string
        required: true
        description: qb64 identifier prefix of contact image to get
      responses:
        '200':
          description: Contact information successfully retrieved for prefix
          content:
            image/jpg:
              schema:
                description: Image
                type: binary
        '404':
          description: No contact information found for prefix
    post:
      summary: Uploads an image to associate with identifier.
      description: Uploads an image to associate with identifier.
      tags:
      - Contacts
      parameters:
      - in: path
        name: prefix
        schema:
          type: string
        description: identifier prefix to associate image to
        required: true
      requestBody:
        required: true
        content:
          image/jpg:
            schema:
              type: string
              format: binary
          image/png:
            schema:
              type: string
              format: binary
      responses:
        '200':
          description: Image successfully uploaded
  /multisig/request/{said}:
    get: {}
  /identifiers/{name}/endroles/{role}:
    get: {}
    post: {}
  /identifiers/{name}/registries/{registryName}:
    get:
      summary: Get a single credential issuance and revocation registy
      description: Get a single credential issuance and revocation registy
      tags:
      - Registries
      responses:
        '200':
          description: credential issuance and revocation registy
  /identifiers/{name}/credentials/{said}:
    delete:
      summary: Perform credential revocation
      description: Perform credential revocation
    get:
      summary: Export credential and all supporting cryptographic material
      description: Export credential and all supporting cryptographic material
      tags:
      - Credentials
      parameters:
      - in: path
        name: aid
        schema:
          type: string
        required: true
        description: The identifier to create
      - in: path
        name: said
        schema:
          type: string
        required: true
        description: SAID of credential to get
      responses:
        '200':
          description: Credential export.
          content:
            application/json+cesr:
              schema:
                description: Credential
                type: object
  /identifiers/{name}/multisig/request:
    post: {}
  /identifiers/{name}/multisig/join:
    post: {}
  /identifiers/{name}/ipex/admit:
    post:
      summary: List credential issuance and revocation registies
      description: List credential issuance and revocation registies
      tags:
      - Registries
      responses:
        '200':
          description: array of current credential issuance and revocation registies
  /identifiers/{name}/ipex/grant:
    post:
      summary: List credential issuance and revocation registies
      description: List credential issuance and revocation registies
      tags:
      - Registries
      responses:
        '200':
          description: array of current credential issuance and revocation registies
  /challenges/{name}/verify/{source}:
    post:
      summary: Sign challenge message and forward to peer identifier
      description: Sign a challenge word list received out of bands and send `exn`
        peer to peer message to recipient
      tags:
      - Challenge/Response
      parameters:
      - in: path
        name: name
        schema:
          type: string
        required: true
        description: Human readable alias for the identifier to create
      requestBody:
        required: true
        content:
          application/json:
            schema:
              description: Challenge response
              properties:
                recipient:
                  type: string
                  description: human readable alias recipient identifier to send signed
                    challenge to
                words:
                  type: array
                  description: challenge in form of word list
                  items:
                    type: string
      responses:
        '202':
          description: Success submission of signed challenge/response
    put:
      summary: Mark challenge response exn message as signed
      description: Mark challenge response exn message as signed
      tags:
      - Challenge/Response
      parameters:
      - in: path
        name: name
        schema:
          type: string
        required: true
        description: Human readable alias for the identifier to create
      requestBody:
        required: true
        content:
          application/json:
            schema:
              description: Challenge response
              properties:
                aid:
                  type: string
                  description: aid of signer of accepted challenge response
                said:
                  type: array
                  description: SAID of challenge message signed
                  items:
                    type: string
      responses:
        '202':
          description: Success submission of signed challenge/response
  /identifiers/{name}/endroles/{role}/{eid}:
    delete: {}
  /oobi:
    get: {}
  /:
    post:
      summary: Accept KERI events with attachment headers and parse
      description: Accept KERI events with attachment headers and parse.
      tags:
      - Events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: KERI event message
      responses:
        '204':
          description: KEL EXN, QRY, RPY event accepted.
    put:
      summary: Accept KERI events with attachment headers and parse
      description: Accept KERI events with attachment headers and parse.
      tags:
      - Events
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              description: KERI event message
      responses:
        '200':
          description: Mailbox query response for server sent events
        '204':
          description: KEL or EXN event accepted.
  /oobi/{aid}:
    get: {}
  /oobi/{aid}/{role}:
    get: {}
  /oobi/{aid}/{role}/{eid}:
    get: {}
info:
  title: KERIA Interactive Web Interface API
  version: 1.0.1
openapi: 3.1.0