AGNTCY App Service API

openapi: 3.2.0
info:
  title: AGNTCY Identity Service App Service API
  description: AGNTCY Identity Service API provides a set of endpoints for managing identity and access control within the Agntcy ecosystem.
  contact:
    name: Agntcy Team
    url: https://github.com/agntcy/identity-service
    email: identity@agntcy.org
  version: v1alpha1
  x-provenance:
    method: harvested
    authored_by: AGNTCY (Outshift by Cisco)
    harvested_by: API Evangelist
    harvested_on: '2026-08-19'
    first_party: true
    provider_published: true
    source_host: agntcy.org / outshift.com
    note: 'Four first-party machine-readable contracts: the Agent Connect Protocol OpenAPI 3.1.1, the OASF Schema API, and two AGNTCY Identity OpenAPI 3.0.3 documents. schema.oasf.outshift.com is the one genuinely callable AGNTCY-hosted API (unauthenticated, 200).'
  x-evidence:
  - type: source
    url: https://spec.acp.agntcy.org/
  - type: source
    url: https://schema.oasf.outshift.com/doc
  - type: source
    url: https://identity-docs.outshift.com/api/openapi/service/v1alpha1/openapi.yaml
servers:
- url: http://localhost:4000
  description: Local environment
security:
- AccessToken: []
  ApiKey: []
tags:
- name: AppService
  description: AppService manages apps.
paths:
  /v1alpha1/apps:
    get:
      tags:
      - AppService
      description: List Apps.
      operationId: AppService_ListApps
      parameters:
      - name: page
        in: query
        description: The current page of the pagination
        schema:
          type: integer
          format: int32
      - name: size
        in: query
        description: The page size of the pagination
        schema:
          type: integer
          format: int32
      - name: query
        in: query
        description: The search query
        schema:
          type: string
      - name: types
        in: query
        description: The app type filter
        schema:
          type: array
          items:
            enum:
            - APP_TYPE_UNSPECIFIED
            - APP_TYPE_AGENT_A2A
            - APP_TYPE_AGENT_OASF
            - APP_TYPE_MCP_SERVER
            type: string
            format: enum
      - name: sortColumn
        in: query
        description: The column ID to sort by
        schema:
          type: string
      - name: sortDesc
        in: query
        description: Whether to sort in descending order (true) or ascending order (false)
        schema:
          type: boolean
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListAppsResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
    post:
      tags:
      - AppService
      description: Create a new App.
      operationId: AppService_CreateApp
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/App'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/App'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
  /v1alpha1/apps/all/count:
    get:
      tags:
      - AppService
      description: Get apps count per type.
      operationId: AppService_GetAppsCount
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetAppsCountResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
  /v1alpha1/apps/oasf:
    post:
      tags:
      - AppService
      operationId: AppService_CreateOasfApp
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateOasfAppRequest'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateOasfAppResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
  /v1alpha1/apps/{appId}:
    get:
      tags:
      - AppService
      description: Get App by id
      operationId: AppService_GetApp
      parameters:
      - name: appId
        in: path
        description: App Id to get.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/App'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
    delete:
      tags:
      - AppService
      description: Delete an existing App.
      operationId: AppService_DeleteApp
      parameters:
      - name: appId
        in: path
        description: App Id to delete.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content: {}
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
    patch:
      tags:
      - AppService
      description: Update an App.
      operationId: AppService_UpdateApp
      parameters:
      - name: appId
        in: path
        description: App Id to update.
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/App'
        required: true
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/App'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
  /v1alpha1/apps/{appId}/api-key/refresh:
    get:
      tags:
      - AppService
      description: Refresh the api-key for an App.
      operationId: AppService_RefreshAppApiKey
      parameters:
      - name: appId
        in: path
        description: App Id to refresh the API Key for.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/App'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
  /v1alpha1/apps/{appId}/badge:
    get:
      tags:
      - AppService
      description: Get the current badge issued for the App.
      operationId: AppService_GetBadge
      parameters:
      - name: appId
        in: path
        description: App Id or Resolver Metadata ID to get the badge for.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Badge'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
  /v1alpha1/tasks:
    get:
      tags:
      - AppService
      description: Get the list of tasks of all apps
      operationId: AppService_GetTasks
      parameters:
      - name: excludeAppIds
        in: query
        description: A filter to exclude fetching tasks for the specified app ids
        schema:
          type: array
          items:
            type: string
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetTasksResponse'
        default:
          description: Default error response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Status'
components:
  schemas:
    Proof:
      type: object
      properties:
        type:
          type: string
          description: The type of the proof
        proofPurpose:
          type: string
          description: The proof purpose
        proofValue:
          type: string
          description: The proof value
      description: "A data integrity proof provides information about the proof mechanism,\n parameters required to verify that proof, and the proof value itself."
    GetAppsCountResponse:
      type: object
      properties:
        counts:
          type: array
          items:
            $ref: '#/components/schemas/AppTypeCountEntry'
          description: The apps count per app type
        total:
          type: string
          description: The total count
    GetTasksResponse_TaskList:
      type: object
      properties:
        tasks:
          type: array
          items:
            $ref: '#/components/schemas/Task'
    Task:
      type: object
      properties:
        id:
          readOnly: true
          type: string
          description: A unique identifier for the Task.
        name:
          readOnly: true
          type: string
          description: A human-readable name for the Task.
        description:
          readOnly: true
          type: string
          description: A human-readable description for the Task.
        appId:
          readOnly: true
          type: string
          description: An application ID for the Task.
        toolName:
          readOnly: true
          type: string
          description: A tool name for the Task.
      description: Identity Service Policy Task
    CredentialStatus:
      type: object
      properties:
        id:
          type: string
          description: The URL identifying the schema file
        type:
          type: string
          description: Type specifies the type of the file
        createdAt:
          type: string
          description: The creation date and time of the status
          format: date-time
        purpose:
          enum:
          - CREDENTIAL_STATUS_PURPOSE_UNSPECIFIED
          - CREDENTIAL_STATUS_PURPOSE_REVOCATION
          type: string
          description: The value of the purpose for the status entry
          format: enum
      description: "CredentialStatus represents the credentialStatus property of a Verifiable Credential.\n more information can be found [here]\n\n [here]: https://www.w3.org/TR/vc-data-model-2.0/#status"
    GetTasksResponse:
      type: object
      properties:
        result:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/GetTasksResponse_TaskList'
          description: The list of tasks per Agentic Service type
    Badge:
      type: object
      properties:
        verifiableCredential:
          $ref: '#/components/schemas/VerifiableCredential'
        appId:
          type: string
    GoogleProtobufAny:
      type: object
      properties:
        '@type':
          type: string
          description: The type of the serialized message.
      additionalProperties: true
      description: Contains an arbitrary serialized message along with a @type that describes the type of the serialized message.
    CredentialSchema:
      type: object
      properties:
        type:
          type: string
          description: Type specifies the type of the file
        id:
          type: string
          description: The URL identifying the schema file
      description: "CredentialSchema represents the credentialSchema property of a Verifiable Credential.\n more information can be found [here]\n\n [here]: https://www.w3.org/TR/vc-data-model-2.0/#data-schemas"
    AppTypeCountEntry:
      type: object
      properties:
        key:
          enum:
          - APP_TYPE_UNSPECIFIED
          - APP_TYPE_AGENT_A2A
          - APP_TYPE_AGENT_OASF
          - APP_TYPE_MCP_SERVER
          type: string
          description: The type of the App
          format: enum
        value:
          type: string
          description: The count of apps of the given type
    CreateOasfAppRequest:
      type: object
      properties:
        schemaBase64:
          type: string
          description: The OASF schema in a base64 encoded format
    PagedResponse:
      type: object
      properties:
        nextPage:
          type: integer
          description: Next page
          format: int32
        hasNextPage:
          type: boolean
          description: Has next page
        total:
          type: string
          description: The total size of items
        size:
          type: integer
          description: The size of the current page
          format: int32
      description: Pagination response
    Status:
      type: object
      properties:
        code:
          type: integer
          description: The status code, which should be an enum value of [google.rpc.Code][google.rpc.Code].
          format: int32
        message:
          type: string
          description: A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
        details:
          type: array
          items:
            $ref: '#/components/schemas/GoogleProtobufAny'
          description: A list of messages that carry the error details.  There is a common set of message types for APIs to use.
      description: 'The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors).'
    CreateOasfAppResponse:
      type: object
      properties:
        app:
          allOf:
          - $ref: '#/components/schemas/App'
          description: The created OASF App.
        badge:
          allOf:
          - $ref: '#/components/schemas/Badge'
          description: The issued badge for the OASF App.
    ListAppsResponse:
      type: object
      properties:
        apps:
          type: array
          items:
            $ref: '#/components/schemas/App'
          description: A list of Apps.
        pagination:
          allOf:
          - $ref: '#/components/schemas/PagedResponse'
          description: Pagination response.
    App:
      required:
      - name
      - type
      type: object
      properties:
        id:
          readOnly: true
          type: string
          description: A unique identifier for the App.
        name:
          type: string
          description: A human-readable name for the App.
        description:
          type: string
          description: A human-readable description for the App.
        type:
          enum:
          - APP_TYPE_UNSPECIFIED
          - APP_TYPE_AGENT_A2A
          - APP_TYPE_AGENT_OASF
          - APP_TYPE_MCP_SERVER
          type: string
          description: The type of the App.
          format: enum
        resolverMetadataId:
          readOnly: true
          type: string
          description: The DID value
        apiKey:
          readOnly: true
          type: string
          description: The API Key Secret for the App.
        status:
          readOnly: true
          enum:
          - APP_STATUS_UNSPECIFIED
          - APP_STATUS_ACTIVE
          - APP_STATUS_PENDING
          - APP_STATUS_REVOKED
          type: string
          description: The status of the App
          format: enum
        createdAt:
          readOnly: true
          type: string
          description: CreatedAt records the timestamp of when the App was initially created
          format: date-time
      description: Identity Service App.
    BadgeClaims:
      type: object
      properties:
        id:
          type: string
          description: "The ID as defined [here]\n\n [here]: https://www.w3.org/TR/vc-data-model/#credential-subject"
        badge:
          type: string
          description: The content of the badge
      description: "BadgeClaims represents the content of a Badge VC defined [here]\n\n [here]: https://spec.identity.agntcy.org/docs/vc/intro/"
    VerifiableCredential:
      type: object
      properties:
        context:
          type: array
          items:
            type: string
          description: https://www.w3.org/TR/vc-data-model/#contexts
        type:
          type: array
          items:
            type: string
          description: https://www.w3.org/TR/vc-data-model/#dfn-type
        issuer:
          type: string
          description: https://www.w3.org/TR/vc-data-model/#issuer
        credentialSubject:
          allOf:
          - $ref: '#/components/schemas/BadgeClaims'
          description: https://www.w3.org/TR/vc-data-model/#credential-subject
        id:
          type: string
          description: https://www.w3.org/TR/vc-data-model/#identifiers
        issuanceDate:
          type: string
          description: https://www.w3.org/TR/vc-data-model/#issuance-date
        expirationDate:
          type: string
          description: https://www.w3.org/TR/vc-data-model/#expiration
        credentialSchema:
          type: array
          items:
            $ref: '#/components/schemas/CredentialSchema'
          description: https://www.w3.org/TR/vc-data-model-2.0/#data-schemas
        credentialStatus:
          type: array
          items:
            $ref: '#/components/schemas/CredentialStatus'
          description: https://www.w3.org/TR/vc-data-model-2.0/#status
        proof:
          allOf:
          - $ref: '#/components/schemas/Proof'
          description: https://w3id.org/security#proof
      description: "DataModel represents the W3C Verifiable Credential Data Model defined [here]\n\n [here]: https://www.w3.org/TR/vc-data-model/"
  securitySchemes:
    AccessToken:
      type: http
      description: An IAM JWT token issued to a user during an OIDC flow.
      scheme: bearer
      bearerFormat: JWT
    ApiKey:
      type: apiKey
      description: An IAM Api key.
      name: x-id-api-key
      in: header