openapi: 3.0.3
info:
  title: Accredible 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.
  - name: Groups
    description: Course or achievement containers that credentials are issued against.
  - name: Designs
    description: Reusable visual specifications for rendering badges and certificates.
  - name: Evidence Items
    description: Supplemental work samples attached to a credential.
  - name: References
    description: Peer, teacher, or manager endorsements attached to a credential.
  - name: Analytics
    description: Issuer-level and per-credential engagement analytics.
  - name: Departments
    description: Independent sub-organizations within an issuer account.
  - name: Team Members
    description: Administrators and roles within the issuer account.
  - name: Issuer
    description: Issuer account details and API token management.
  - name: SSO
    description: Recipient single sign-on link generation.
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'
  /credentials/analytics/{id}:
    post:
      operationId: getCredentialAnalytics
      tags: [Analytics]
      summary: View credential analytics
      description: Returns engagement analytics for a single credential.
      parameters:
        - $ref: '#/components/parameters/CredentialId'
      responses:
        '200':
          description: Per-credential analytics.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /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.
  /issuer/groups:
    post:
      operationId: createGroup
      tags: [Groups]
      summary: Create a group
      description: Creates a new Group (course or achievement) under the issuer account.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                group:
                  $ref: '#/components/schemas/GroupInput'
      responses:
        '200':
          description: The created group.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
  /issuer/groups/{group_id}:
    parameters:
      - $ref: '#/components/parameters/GroupId'
    get:
      operationId: getGroup
      tags: [Groups]
      summary: View a group
      description: Retrieves a single Group by ID.
      responses:
        '200':
          description: The requested group.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GroupEnvelope'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateGroup
      tags: [Groups]
      summary: Update a group
      description: Updates an existing Group.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                group:
                  $ref: '#/components/schemas/GroupInput'
      responses:
        '200':
          description: The updated group.
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteGroup
      tags: [Groups]
      summary: Delete a group
      description: Deletes a Group by ID.
      responses:
        '200':
          description: The group was deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /issuer/all_groups:
    get:
      operationId: listAllGroups
      deprecated: true
      tags: [Groups]
      summary: View all groups (deprecated)
      description: Lists all Groups under the issuer account. Deprecated in favor of search.
      parameters:
        - name: name
          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 groups.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /issuer/groups/search:
    post:
      operationId: searchGroups
      tags: [Groups]
      summary: Search for groups
      description: Searches Groups by name and other attributes with pagination.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name: { type: string }
                page: { type: integer }
                page_size: { type: integer }
      responses:
        '200':
          description: Matching groups.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /designs:
    get:
      operationId: listDesigns
      deprecated: true
      tags: [Designs]
      summary: View all designs (deprecated)
      description: Lists Designs, optionally filtered by kind and department.
      parameters:
        - name: kind
          in: query
          schema: { type: string, enum: [certificate, badge] }
        - name: department_id
          in: query
          schema: { type: integer }
      responses:
        '200':
          description: A list of designs.
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createDesign
      tags: [Designs]
      summary: Create a design
      description: Creates a new visual Design for badges or certificates.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                design:
                  $ref: '#/components/schemas/DesignInput'
      responses:
        '200':
          description: The created design.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /designs/{design_id}:
    parameters:
      - $ref: '#/components/parameters/DesignId'
    get:
      operationId: getDesign
      tags: [Designs]
      summary: View a design
      description: Retrieves a single Design by ID.
      responses:
        '200':
          description: The requested design.
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateDesign
      tags: [Designs]
      summary: Update a design
      description: Updates an existing Design.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                design:
                  $ref: '#/components/schemas/DesignInput'
      responses:
        '200':
          description: The updated design.
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteDesign
      tags: [Designs]
      summary: Delete a design
      description: Deletes a Design by ID.
      responses:
        '200':
          description: The design was deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /designs/{design_id}/copy:
    post:
      operationId: copyDesign
      tags: [Designs]
      summary: Copy a design
      description: Creates a duplicate of an existing Design.
      parameters:
        - $ref: '#/components/parameters/DesignId'
      responses:
        '200':
          description: The copied design.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /designs/search:
    post:
      operationId: searchDesigns
      tags: [Designs]
      summary: Search for designs
      description: Searches Designs by name, kind, and other attributes.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name: { type: string }
                kind: { type: string, enum: [certificate, badge] }
                page: { type: integer }
                page_size: { type: integer }
      responses:
        '200':
          description: Matching designs.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /designs/{design_id}/preview:
    post:
      operationId: previewDesign
      tags: [Designs]
      summary: Preview a design
      description: Renders a preview image of a Design with sample data.
      parameters:
        - $ref: '#/components/parameters/DesignId'
      responses:
        '200':
          description: A design preview.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /designers/badge/initialize:
    post:
      operationId: initializeBadgeDesigner
      tags: [Designs]
      summary: Initialize embedded badge designer
      description: Returns a session for the embedded badge designer experience.
      responses:
        '200':
          description: An embedded badge designer session.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /designers/certificate/initialize:
    post:
      operationId: initializeCertificateDesigner
      tags: [Designs]
      summary: Initialize embedded certificate designer
      description: Returns a session for the embedded certificate designer experience.
      responses:
        '200':
          description: An embedded certificate designer session.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /departments/search:
    post:
      operationId: searchDepartments
      tags: [Departments]
      summary: Search for departments
      description: >-
        Searches Departments - independent sub-organizations, each with their
        own Designs, Groups, and branding.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                name: { type: string }
                page: { type: integer }
                page_size: { type: integer }
      responses:
        '200':
          description: Matching departments.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /credentials/{credential_id}/evidence_items:
    post:
      operationId: createEvidenceItem
      tags: [Evidence Items]
      summary: Create an evidence item
      description: Attaches a new Evidence Item (work sample or artifact) to a credential.
      parameters:
        - $ref: '#/components/parameters/CredentialIdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                evidence_item:
                  $ref: '#/components/schemas/EvidenceItemInput'
      responses:
        '200':
          description: The created evidence item.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /credentials/{credential_id}/evidence_items/{evidence_item_id}:
    parameters:
      - $ref: '#/components/parameters/CredentialIdPath'
      - name: evidence_item_id
        in: path
        required: true
        schema: { type: integer }
    get:
      operationId: getEvidenceItem
      tags: [Evidence Items]
      summary: View an evidence item
      description: Retrieves a single Evidence Item on a credential.
      responses:
        '200':
          description: The requested evidence item.
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateEvidenceItem
      tags: [Evidence Items]
      summary: Update an evidence item
      description: Updates an Evidence Item on a credential.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                evidence_item:
                  $ref: '#/components/schemas/EvidenceItemInput'
      responses:
        '200':
          description: The updated evidence item.
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteEvidenceItem
      tags: [Evidence Items]
      summary: Delete an evidence item
      description: Deletes an Evidence Item from a credential.
      responses:
        '200':
          description: The evidence item was deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /credentials/{credential_id}/references:
    post:
      operationId: createReference
      tags: [References]
      summary: Create a reference
      description: Attaches a new Reference (endorsement) to a credential.
      parameters:
        - $ref: '#/components/parameters/CredentialIdPath'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                reference:
                  $ref: '#/components/schemas/ReferenceInput'
      responses:
        '200':
          description: The created reference.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /credentials/{credential_id}/references/{reference_id}:
    parameters:
      - $ref: '#/components/parameters/CredentialIdPath'
      - name: reference_id
        in: path
        required: true
        schema: { type: integer }
    get:
      operationId: getReference
      tags: [References]
      summary: View a reference
      description: Retrieves a single Reference on a credential.
      responses:
        '200':
          description: The requested reference.
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateReference
      tags: [References]
      summary: Update a reference
      description: Updates a Reference on a credential.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                reference:
                  $ref: '#/components/schemas/ReferenceInput'
      responses:
        '200':
          description: The updated reference.
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteReference
      tags: [References]
      summary: Delete a reference
      description: Deletes a Reference from a credential.
      responses:
        '200':
          description: The reference was deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /analytics:
    get:
      operationId: indexAnalytics
      tags: [Analytics]
      summary: Index analytics
      description: Returns issuer-level engagement analytics across credentials.
      responses:
        '200':
          description: Issuer analytics.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /team_members:
    post:
      operationId: createTeamMember
      tags: [Team Members]
      summary: Create a team member
      description: Adds a new Team Member (administrator) to the issuer account.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                team_member:
                  $ref: '#/components/schemas/TeamMemberInput'
      responses:
        '200':
          description: The created team member.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /team_members/{id}:
    parameters:
      - name: id
        in: path
        required: true
        schema: { type: integer }
    get:
      operationId: getTeamMember
      tags: [Team Members]
      summary: View a team member
      description: Retrieves a single Team Member by ID.
      responses:
        '200':
          description: The requested team member.
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateTeamMember
      tags: [Team Members]
      summary: Update a team member
      description: Updates a Team Member's details or role.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                team_member:
                  $ref: '#/components/schemas/TeamMemberInput'
      responses:
        '200':
          description: The updated team member.
        '401':
          $ref: '#/components/responses/Unauthorized'
    delete:
      operationId: deleteTeamMember
      tags: [Team Members]
      summary: Delete a team member
      description: Removes a Team Member from the issuer account.
      responses:
        '200':
          description: The team member was deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /issuer/details:
    get:
      operationId: getIssuerDetails
      tags: [Issuer]
      summary: View an issuer
      description: Returns details about the authenticated issuer account.
      responses:
        '200':
          description: Issuer details.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /sso/generate_link:
    post:
      operationId: generateSsoLink
      tags: [SSO]
      summary: Generate recipient SSO link
      description: >-
        Generates a single sign-on link that lets a recipient access their
        credentials.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                recipient_email: { type: string }
                recipient_id: { type: string }
      responses:
        '200':
          description: A recipient SSO link.
        '401':
          $ref: '#/components/responses/Unauthorized'
  /api/generate_token:
    post:
      operationId: generateApiToken
      tags: [Issuer]
      summary: Update API key
      description: Rotates the API token for the issuer account.
      responses:
        '200':
          description: A new API token.
        '401':
          $ref: '#/components/responses/Unauthorized'
components:
  securitySchemes:
    tokenAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        API key sent in the Authorization header using the scheme
        `Token token=YOUR_API_KEY`.
  parameters:
    CredentialId:
      name: id
      in: path
      required: true
      description: The unique ID of the credential.
      schema: { type: integer }
    CredentialIdPath:
      name: credential_id
      in: path
      required: true
      description: The unique ID of the credential.
      schema: { type: integer }
    GroupId:
      name: group_id
      in: path
      required: true
      description: The unique ID of the group.
      schema: { type: integer }
    DesignId:
      name: design_id
      in: path
      required: true
      description: The unique ID of the design.
      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'
  schemas:
    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. }
    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. }
        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.
    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 }
    CredentialEnvelope:
      type: object
      properties:
        credential:
          $ref: '#/components/schemas/Credential'
    GroupInput:
      type: object
      properties:
        name: { type: string, description: The internal name of the group. }
        course_name: { type: string, description: The course/achievement name shown to recipients. }
        course_description: { type: string, description: The course/achievement description. }
        design_id: { type: integer, description: The Design used to render credentials in this group. }
        language: { type: string, description: The language code for the group. }
    Group:
      allOf:
        - $ref: '#/components/schemas/GroupInput'
        - type: object
          properties:
            id: { type: integer, description: The unique group ID. }
    GroupEnvelope:
      type: object
      properties:
        group:
          $ref: '#/components/schemas/Group'
    DesignInput:
      type: object
      properties:
        name: { type: string, description: The name of the design. }
        kind: { type: string, enum: [certificate, badge], description: Whether the design renders a certificate or a badge. }
        department_id: { type: integer, description: The department the design belongs to. }
    EvidenceItemInput:
      type: object
      properties:
        description: { type: string, description: A description of the evidence. }
        category: { type: string, description: The category of the evidence item. }
        string_object: { type: string, description: A text value for the evidence. }
        file: { type: string, description: A file URL or upload reference for the evidence. }
        hidden: { type: boolean, description: Whether the evidence item is hidden. }
    ReferenceInput:
      type: object
      properties:
        name: { type: string, description: The name of the person giving the reference. }
        email: { type: string, description: The email of the referee. }
        body: { type: string, description: The reference text. }
        hidden: { type: boolean, description: Whether the reference is hidden. }
    TeamMemberInput:
      type: object
      properties:
        name: { type: string, description: The team member's name. }
        email: { type: string, description: The team member's email address. }
        role: { type: string, description: The team member's role. }
    Error:
      type: object
      properties:
        error: { type: string, description: A human-readable error message. }
        errors:
          type: array
          items: { type: string }