Inbox Academy Learning API

openapi: 3.2.0
info:
  title: Inbox Academy Learning API
  version: 1.0.0
  description: Organization-scoped API authenticated with an organization API key. Every request acts on the organization its key was issued for.
tags:
- name: Learning
paths:
  /learning/api/v1/enrollments/:
    post:
      summary: Enrol an email address in a course
      operationId: createEnrollment
      description: 'Creates an enrollment. By default it is created already verified: it starts active, no verification email is sent, and the first content is scheduled immediately — the caller is trusted to have established that the address is the learner''s. Send `verified: false` to instead email the learner a verification link and start the enrollment as unverified, becoming active once they confirm. The course is resolved against the organization the API key was issued for, so a slug belonging to another organization is reported as not found. The course must be enabled, but — unlike the embeddable public endpoint — it does not need to be public. A verified enrollment additionally requires the course to have at least one published content, since there would otherwise be nothing to schedule.'
      security:
      - organizationApiKey:
        - enrollments:create
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/EnrollmentCreateRequest'
      responses:
        '200':
          description: A non-deactivated enrollment already exists for this learner and course; nothing was created and no email was sent.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AlreadyEnrolledResponse'
        '201':
          description: Enrollment created — active, or pending the learner's verification if `verified` was false.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnrollmentCreatedResponse'
        '400':
          description: The request body is malformed or fails validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The API key is missing, malformed, unknown, revoked or expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The key lacks the required scope or is not an organization key; or the email is blocked, or the organization is at its learner cap.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorWithReferenceResponse'
        '404':
          description: No enabled course with that slug in this organization.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: The key's request budget for the current window is exhausted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '500':
          description: The enrollment could not be completed and nothing was created; safe to retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorWithReferenceResponse'
      tags:
      - Learning
  /learning/api/v1/enrollments/{enrollment_id}/unlock/:
    post:
      summary: Unlock a gate for an enrollment
      operationId: unlockGate
      description: 'A gate is a step in a course that holds a learner until something outside the course happens - a payment, an account being created, a form being submitted. This call is that signal. If the learner is waiting at the gate they move on to the rest of the course straight away; if they have not reached it yet, the unlock is kept and they pass through without stopping when they do. Calling it again for a gate that is already unlocked changes nothing, so it is safe to retry. The enrollment may be unverified or active, but not completed or deactivated. A course can also gate its enrollments: naming its enrollment gate key here confirms an unverified enrollment, which becomes active, gets its first content scheduled and is sent the course''s welcome email.'
      parameters:
      - name: enrollment_id
        in: path
        required: true
        schema:
          type: integer
      security:
      - organizationApiKey:
        - enrollments:update
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GateUnlockRequest'
      responses:
        '200':
          description: The gate is unlocked for this enrollment.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GateUnlockResponse'
        '400':
          description: The request body is malformed or fails validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: The API key is missing, malformed, unknown, revoked or expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The key lacks the required scope or is not an organization key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: No enrollment with that id in this organization, or no gate with that key in its course.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: The enrollment has ended, or no gate was named and the learner is not waiting at one.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: The key's request budget for the current window is exhausted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Learning
  /learning/api/v1/ping/:
    get:
      summary: Check that an API key authenticates
      operationId: ping
      description: Returns 200 for any valid, non-revoked, unexpired organization API key, whichever scopes it carries. Reads and changes nothing, so it is safe to call as a credential or connectivity check. It is rate limited like every other endpoint.
      security:
      - organizationApiKey: []
      responses:
        '200':
          description: The API key is valid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PingResponse'
        '401':
          description: The API key is missing, malformed, unknown, revoked or expired.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: The key is not an organization key.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: The key's request budget for the current window is exhausted.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      tags:
      - Learning
components:
  schemas:
    GateUnlockResponse:
      properties:
        status:
          description: '`unlocked`: the learner was waiting at the gate and has moved on. `unlocked_in_advance`: the learner has not reached the gate yet and will pass it without stopping. `already_unlocked`: nothing changed; the gate was unlocked before. For an enrollment gate, `unlocked` means the enrollment is now active, and `already_unlocked` that it already was.'
          enum:
          - unlocked
          - unlocked_in_advance
          - already_unlocked
          title: Status
          type: string
        gate:
          description: The key of the gate that was unlocked.
          title: Gate
          type: string
        enrollment:
          $ref: '#/components/schemas/EnrollmentResponse'
      required:
      - status
      - gate
      - enrollment
      title: GateUnlockResponse
      type: object
    GateUnlockRequest:
      properties:
        gate:
          anyOf:
          - maxLength: 100
            minLength: 1
            type: string
          - type: 'null'
          default: null
          description: 'The key of the gate to unlock. Naming it is recommended: it also unlocks a gate the learner has not reached yet, so they pass straight through when they get there, and a late or retried call can never open a different gate than the one it was meant for. When omitted, the gate the learner is currently waiting at is unlocked. Naming the course''s enrollment gate key confirms an enrollment that is waiting to be confirmed.'
          examples:
          - payment
          title: Gate
      title: GateUnlockRequest
      type: object
    EnrollmentResponse:
      properties:
        id:
          description: The unique identifier of the enrollment.
          minimum: 1
          title: Id
          type: integer
        email:
          description: The email address of the learner to be enrolled.
          title: Email
          type: string
        course_slug:
          description: The slug of the course the learner is enrolled in.
          title: Course Slug
          type: string
        status:
          description: The status of the enrollment.
          title: Status
          type: string
        enrolled_at:
          description: The timestamp when the learner was enrolled.
          format: date-time
          title: Enrolled At
          type: string
        activated_at:
          anyOf:
          - format: date-time
            type: string
          - type: 'null'
          default: null
          description: The timestamp when the enrollment was activated.
          title: Activated At
        waiting_at_gate:
          anyOf:
          - type: string
          - type: 'null'
          default: null
          description: The key of the gate the learner is waiting at, if their progress is held at one. The enrollment's status stays `active` while it waits - except at a course's enrollment gate, which holds the enrollment `unverified` until it is unlocked.
          title: Waiting At Gate
      required:
      - id
      - email
      - course_slug
      - status
      - enrolled_at
      title: EnrollmentResponse
      type: object
    PingResponse:
      properties:
        status:
          const: ok
          default: ok
          title: Status
          type: string
      title: PingResponse
      type: object
    EnrollmentCreateRequest:
      properties:
        email:
          title: Email
          type: string
        course_slug:
          minLength: 1
          title: Course Slug
          type: string
        subscribe_to_newsletter:
          default: false
          description: Whether the learner should be subscribed to the newsletter.
          title: Subscribe To Newsletter
          type: boolean
        verified:
          default: true
          description: 'Whether the enrollment is created already verified. A verified enrollment starts active and its first content is scheduled straight away, with no verification email. Set to false to have the learner confirm their address first: the enrollment then starts unverified and becomes active once they follow the emailed link. In a course whose enrollments are gated, false instead sends the course''s enrollment email and the enrollment waits at the enrollment gate until it is unlocked.'
          title: Verified
          type: boolean
      required:
      - email
      - course_slug
      title: EnrollmentCreateRequest
      type: object
    ErrorWithReferenceResponse:
      description: 'Errors whose detail is withheld from the caller and logged instead.


        `error_id` correlates the response an integrator reports back to the full

        detail in the server logs - see `django_email_learning.error_responses`.'
      properties:
        error:
          title: Error
          type: string
        error_id:
          title: Error Id
          type: string
      required:
      - error
      - error_id
      title: ErrorWithReferenceResponse
      type: object
    ErrorResponse:
      properties:
        error:
          title: Error
          type: string
      required:
      - error
      title: ErrorResponse
      type: object
    AlreadyEnrolledResponse:
      properties:
        status:
          const: already_enrolled
          default: already_enrolled
          title: Status
          type: string
      title: AlreadyEnrolledResponse
      type: object
    EnrollmentCreatedResponse:
      properties:
        status:
          const: enrolled
          default: enrolled
          title: Status
          type: string
        enrollment:
          anyOf:
          - $ref: '#/components/schemas/EnrollmentResponse'
          - type: 'null'
          default: null
      title: EnrollmentCreatedResponse
      type: object
  securitySchemes:
    organizationApiKey:
      type: http
      scheme: bearer
      description: 'An organization API key, sent as `Authorization: Bearer elk_<key_id>_<secret>`. The listed scopes must all be present on the key.'