openapi: 3.0.3
info:
  title: Credly Web Service Badge Templates API
  description: 'The Credly Web Service API lets an issuing organization manage verifiable digital credentials (Open Badges) on the Credly platform, owned by Pearson. Organizations create and manage badge templates, issue and revoke badges to recipients, read organization and employee data, pull an events feed, and expose recipient credentials through Open Badges Infrastructure (OBI) endpoints. All calls are scoped to an organization via the organization_id path parameter.


    Authentication is either HTTP Basic - the organization''s authorization_token as the username with a blank password (Base64-encoded in the Authorization header) - or OAuth 2.0 using the client_credentials grant against https://api.credly.com/oauth/token, sending the resulting Bearer token.


    Real-time notifications are delivered as outbound webhooks (Credly POSTs a JSON object to a configured HTTPS URL). There is no public WebSocket API.


    Endpoints marked "confirmed" were verified against Credly''s live developer documentation; endpoints marked "modeled" follow Credly''s documented, consistent /v1/organizations/{organization_id}/... REST conventions and should be reconciled against the current API reference before production use.'
  version: '1.0'
  contact:
    name: Credly (Pearson)
    url: https://credly.com
servers:
- url: https://api.credly.com/v1
  description: Production
- url: https://sandbox-api.credly.com/v1
  description: Sandbox
security:
- basicAuth: []
- oauth2: []
tags:
- name: Badge Templates
  description: Reusable credential designs badges are issued against.
paths:
  /organizations/{organization_id}/badge_templates:
    get:
      operationId: listBadgeTemplates
      tags:
      - Badge Templates
      summary: List badge templates
      description: Returns a paginated list of the organization's badge templates. (confirmed)
      parameters:
      - $ref: '#/components/parameters/OrganizationId'
      - $ref: '#/components/parameters/Page'
      - name: filter
        in: query
        required: false
        schema:
          type: string
        description: Filter expression, e.g. state::active.
      - name: sort
        in: query
        required: false
        schema:
          type: string
      responses:
        '200':
          description: A paginated list of badge templates.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadgeTemplateList'
        '401':
          $ref: '#/components/responses/Unauthorized'
    post:
      operationId: createBadgeTemplate
      tags:
      - Badge Templates
      summary: Create a badge template
      description: Creates a new badge template for the organization. (modeled)
      parameters:
      - $ref: '#/components/parameters/OrganizationId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BadgeTemplateInput'
      responses:
        '200':
          description: The created badge template.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadgeTemplateEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '422':
          $ref: '#/components/responses/UnprocessableEntity'
  /organizations/{organization_id}/badge_templates/{id}:
    get:
      operationId: getBadgeTemplate
      tags:
      - Badge Templates
      summary: Retrieve a badge template
      description: Returns a single badge template by ID. (modeled)
      parameters:
      - $ref: '#/components/parameters/OrganizationId'
      - $ref: '#/components/parameters/Id'
      responses:
        '200':
          description: The badge template.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadgeTemplateEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    put:
      operationId: updateBadgeTemplate
      tags:
      - Badge Templates
      summary: Update a badge template
      description: Updates an existing badge template. (modeled)
      parameters:
      - $ref: '#/components/parameters/OrganizationId'
      - $ref: '#/components/parameters/Id'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BadgeTemplateInput'
      responses:
        '200':
          description: The updated badge template.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadgeTemplateEnvelope'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
    delete:
      operationId: deleteBadgeTemplate
      tags:
      - Badge Templates
      summary: Delete a badge template
      description: Deletes a badge template. (modeled)
      parameters:
      - $ref: '#/components/parameters/OrganizationId'
      - $ref: '#/components/parameters/Id'
      responses:
        '200':
          description: The badge template was deleted.
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  schemas:
    BadgeTemplateEnvelope:
      type: object
      properties:
        data:
          $ref: '#/components/schemas/BadgeTemplate'
    Metadata:
      type: object
      description: Pagination and response metadata.
      properties:
        count:
          type: integer
        current_page:
          type: integer
        total_count:
          type: integer
        total_pages:
          type: integer
        per:
          type: integer
    BadgeTemplateInput:
      type: object
      required:
      - name
      - description
      properties:
        name:
          type: string
        description:
          type: string
        image:
          type: string
          description: Base64-encoded image or image URL.
        skills:
          type: array
          items:
            type: string
        badge_template_activity_type:
          type: string
    BadgeTemplateList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/BadgeTemplate'
        metadata:
          $ref: '#/components/schemas/Metadata'
    Error:
      type: object
      properties:
        errors:
          type: array
          items:
            type: object
            properties:
              message:
                type: string
              field:
                type: string
    BadgeTemplate:
      type: object
      properties:
        id:
          type: string
        name:
          type: string
        description:
          type: string
        image_url:
          type: string
        state:
          type: string
          enum:
          - active
          - archived
          - draft
        skills:
          type: array
          items:
            type: object
        created_at:
          type: string
          format: date-time
  parameters:
    Page:
      name: page
      in: query
      required: false
      description: The page number of paginated results.
      schema:
        type: integer
        minimum: 1
        default: 1
    OrganizationId:
      name: organization_id
      in: path
      required: true
      description: The ID of the issuing organization.
      schema:
        type: string
    Id:
      name: id
      in: path
      required: true
      description: The resource ID.
      schema:
        type: string
  responses:
    Unauthorized:
      description: Authentication failed or was not provided.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnprocessableEntity:
      description: The request was well-formed but could not be processed.
      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:
    basicAuth:
      type: http
      scheme: basic
      description: HTTP Basic Authentication using the organization's authorization_token as the username and a blank password.
    oauth2:
      type: oauth2
      description: OAuth 2.0 client_credentials grant. Tokens are short-lived (2 hours) and sent as a Bearer token.
      flows:
        clientCredentials:
          tokenUrl: https://api.credly.com/oauth/token
          scopes:
            read: Read access to organization resources.
            issue: Issue and manage badges.
            workforce: Access to employee/workforce data.