openapi: 3.0.3
info:
  title: Accredible Analytics Credentials API
  description: The Accredible API issues, manages, and verifies digital credentials - certificates and Open Badges - programmatically. Credentials are issued to a recipient against a Group (a course or achievement) and rendered with a reusable Design. The API also manages Evidence Items and References attached to credentials, generates credential PDFs and blockchain-verifiable records, returns engagement analytics, administers Departments and Team Members, and generates recipient SSO links. All requests are authenticated with an API key sent in the Authorization header using the scheme `Token token=YOUR_API_KEY`. Production base URL is https://api.accredible.com/v1; a sandbox is available at https://sandbox.api.accredible.com/v1. Endpoints and paths are grounded in Accredible's published API reference; request and response schemas are modeled and simplified.
  version: '1.0'
  contact:
    name: Accredible
    url: https://www.accredible.com
  license:
    name: Proprietary
    url: https://www.accredible.com/terms-of-service
servers:
- url: https://api.accredible.com/v1
  description: Production
- url: https://sandbox.api.accredible.com/v1
  description: Sandbox
security:
- tokenAuth: []
tags:
- name: Credentials
  description: Issue, retrieve, update, delete, search, and verify digital credentials.
paths:
  /credentials:
    post:
      operationId: createCredential
      tags:
      - Credentials
      summary: Create a credential
      description: Issues a new credential (certificate or badge) to a recipient against a Group, optionally with custom attributes, evidence items, and references.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - credential
              properties:
                credential:
                  $ref: '#/components/schemas/CredentialInput'
      responses:
        '200':
          description: The created credential.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /credentials/bulk_create:
    post:
      operationId: bulkCreateCredentials
      tags:
      - Credentials
      summary: Bulk create credentials
      description: Issues many credentials in a single request.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                credentials:
                  type: array
                  items:
                    $ref: '#/components/schemas/CredentialInput'
      responses:
        '200':
          description: The created credentials.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /credentials/{id}:
    parameters:
    - $ref: '#/components/parameters/CredentialId'
    get:
      operationId: getCredential
      tags:
      - Credentials
      summary: View a credential
      description: Retrieves a single credential by its ID.
      responses:
        '200':
          description: The requested credential.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateCredential
      tags:
      - Credentials
      summary: Update a credential
      description: Updates an existing credential.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                credential:
                  $ref: '#/components/schemas/CredentialInput'
      responses:
        '200':
          description: The updated credential.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CredentialEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteCredential
      tags:
      - Credentials
      summary: Delete a credential
      description: Deletes a credential by ID.
      responses:
        '200':
          description: The credential was deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /credentials/search:
    post:
      operationId: searchCredentials
      tags:
      - Credentials
      summary: Search for credentials
      description: Searches credentials by group, recipient email, recipient ID, and other attributes, with pagination.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                group_id:
                  type: integer
                email:
                  type: string
                recipient_id:
                  type: string
                page:
                  type: integer
                page_size:
                  type: integer
      responses:
        '200':
          description: Matching credentials.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /all_credentials:
    get:
      operationId: listAllCredentials
      deprecated: true
      tags:
      - Credentials
      summary: View many credentials (deprecated)
      description: Lists credentials filtered by group, email, or recipient. Deprecated in favor of the search endpoint.
      parameters:
      - name: group_id
        in: query
        schema:
          type: integer
      - name: email
        in: query
        schema:
          type: string
      - name: recipient_id
        in: query
        schema:
          type: string
      - name: page
        in: query
        schema:
          type: integer
      - name: page_size
        in: query
        schema:
          type: integer
      responses:
        '200':
          description: A list of credentials.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /credentials/generate_pdf:
    post:
      operationId: generateCredentialPdfs
      tags:
      - Credentials
      summary: Generate PDFs for credentials
      description: Generates certificate PDFs for a set of credentials.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                credential_ids:
                  type: array
                  items:
                    type: integer
      responses:
        '200':
          description: PDF generation result.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /credentials/generate_single_pdf/{id}:
    parameters:
    - $ref: '#/components/parameters/CredentialId'
    post:
      operationId: generateSingleCredentialPdf
      tags:
      - Credentials
      summary: Generate PDF for a single credential
      description: Generates a certificate PDF for one credential.
      responses:
        '200':
          description: PDF generation result.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /credentials/blockchain_data/{encoded_id}:
    get:
      operationId: getBlockchainCredential
      tags:
      - Credentials
      summary: Verify blockchain credential
      description: Returns the blockchain verification record for an encoded credential ID.
      parameters:
      - name: encoded_id
        in: path
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Blockchain verification data.
        '404':
          $ref: '#/components/responses/NotFound'
  /issuer/credential_redirect:
    get:
      operationId: credentialRedirect
      tags:
      - Credentials
      summary: Redirect to a credential
      description: Resolves and redirects to a credential's public page.
      parameters:
      - name: issuer_id
        in: query
        schema:
          type: integer
      - name: id
        in: query
        schema:
          type: string
      responses:
        '302':
          description: Redirect to the credential page.
components:
  schemas:
    Credential:
      allOf:
      - $ref: '#/components/schemas/CredentialInput'
      - type: object
        properties:
          id:
            type: integer
            description: The unique credential ID.
          url:
            type: string
            description: The public credential page URL.
          created_at:
            type: string
            format: date-time
    CredentialInput:
      type: object
      required:
      - group_id
      properties:
        recipient:
          $ref: '#/components/schemas/Recipient'
        group_id:
          type: integer
          description: The Group the credential belongs to.
        group_name:
          type: string
          description: The Group name
          usable in place of a Group ID.: null
        name:
          type: string
          description: The credential/course name shown to recipients.
        description:
          type: string
          description: The credential/course description shown to recipients.
        issued_on:
          type: string
          description: 'Date of issue. Format: DD/MM/YYYY.'
        expired_on:
          type: string
          description: 'Expiry date. Format: DD/MM/YYYY.'
        complete:
          type: boolean
          description: Whether the achievement is complete.
        private:
          type: boolean
          description: Whether the credential is private.
        custom_attributes:
          type: object
          description: Custom variables displayed on the credential's design.
        meta_data:
          type: object
          description: Arbitrary key-value strings stored on the credential.
    CredentialEnvelope:
      type: object
      properties:
        credential:
          $ref: '#/components/schemas/Credential'
    Error:
      type: object
      properties:
        error:
          type: string
          description: A human-readable error message.
        errors:
          type: array
          items:
            type: string
    Recipient:
      type: object
      properties:
        name:
          type: string
          description: The recipient's name.
        email:
          type: string
          description: The recipient's email address.
        id:
          type: string
          description: The recipient's ID as defined by your organization.
  parameters:
    CredentialId:
      name: id
      in: path
      required: true
      description: The unique ID of the credential.
      schema:
        type: integer
  responses:
    Unauthorized:
      description: Invalid or missing API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  securitySchemes:
    tokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: API key sent in the Authorization header using the scheme `Token token=YOUR_API_KEY`.