openapi: 3.2.0
info:
  title: Ironfang Rig Projects API
  version: 0.1.0
  summary: Disposable inboxes, callback URLs, mock endpoints and connector routes for integration tests.
  description: 'Ironfang Rig gives an application under test a disposable external

    world: temporary inbox addresses, public callback URLs, mock HTTP

    endpoints and connector routes, allocated fresh for every run, with an

    append-only, sequenced timeline of everything Ironfang observed.'
  contact:
    name: Ironfang
    email: hello@ironfang.uk
    url: https://ironfang.com/contact
  termsOfService: https://ironfang.com/legal/terms
  license:
    name: Proprietary - use governed by the Ironfang terms of service
    url: https://ironfang.com/legal/terms
servers:
- url: https://api.ironfang.com/rig
security:
- apiKey: []
- bearerAuth: []
tags:
- name: Projects
  description: Persistent containers for one application or product.
paths:
  /v1/projects:
    get:
      tags:
      - Projects
      operationId: listProjects
      summary: List projects
      description: Returns the organisation's projects, newest first, as a bounded keyset page. Read-only; no side effects.
      parameters:
      - $ref: '#/components/parameters/Cursor'
      - $ref: '#/components/parameters/Limit'
      responses:
        '200':
          description: A page of projects
          content:
            application/json:
              schema:
                type: object
                required:
                - projects
                properties:
                  projects:
                    type: array
                    items:
                      $ref: '#/components/schemas/Project'
                  next_cursor:
                    type: string
                    description: Opaque cursor for the next page; empty on the last page.
        '400':
          $ref: '#/components/responses/InvalidQuery'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
    post:
      tags:
      - Projects
      operationId: createProject
      summary: Create a project
      description: Creates a project. The slug is unique within the organisation and appears in nothing public. Needs rig.write.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - slug
              - name
              additionalProperties: false
              properties:
                slug:
                  type: string
                  pattern: ^[a-z0-9][a-z0-9-]{0,62}$
                  example: ironfang-platform
                name:
                  type: string
                  maxLength: 120
                  example: Ironfang Platform
      responses:
        '201':
          description: Project created
          content:
            application/json:
              schema:
                type: object
                required:
                - project
                properties:
                  project:
                    $ref: '#/components/schemas/Project'
        '400':
          $ref: '#/components/responses/InvalidJSON'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          $ref: '#/components/responses/Conflict'
        '422':
          $ref: '#/components/responses/InvalidRequest'
  /v1/projects/{projectId}:
    parameters:
    - $ref: '#/components/parameters/ProjectId'
    get:
      tags:
      - Projects
      operationId: getProject
      summary: Get a project
      description: Returns one project. Another organisation's project is not found.
      responses:
        '200':
          description: The project
          content:
            application/json:
              schema:
                type: object
                required:
                - project
                properties:
                  project:
                    $ref: '#/components/schemas/Project'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
components:
  parameters:
    Cursor:
      name: cursor
      in: query
      required: false
      description: The next_cursor of the previous page.
      schema:
        type: string
    Limit:
      name: limit
      in: query
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 50
    ProjectId:
      name: projectId
      in: path
      required: true
      schema:
        type: string
        format: uuid
  responses:
    InvalidJSON:
      description: The body is not one strict JSON value of the documented shape (`invalid_json`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: No such object in this organisation (`not_found`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Conflict:
      description: A name is already taken, or the target is archived (`conflict`, `archived`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InvalidRequest:
      description: A field is invalid; the message names it (`invalid_request`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: The credential lacks the permission or scope, or names another organisation (`forbidden`, `insufficient_scope`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    InvalidQuery:
      description: An unknown, repeated or malformed query parameter (`invalid_query`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: No credential, an invalid one, or a delegated token where none is accepted (`unauthorized`, `invalid_api_key`, `delegated_not_allowed`).
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
  schemas:
    Project:
      type: object
      required:
      - id
      - organisation_id
      - slug
      - name
      - created_at
      properties:
        id:
          type: string
          format: uuid
        organisation_id:
          type: string
          format: uuid
        slug:
          type: string
        name:
          type: string
        created_at:
          type: string
          format: date-time
        archived_at:
          type: string
          format: date-time
    Error:
      type: object
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
            message:
              type: string
            docs:
              type: string
              format: uri
              description: Where the API and its error codes are documented.
        request_id:
          type: string
          description: The X-Ironfang-Request-ID of the failed request.
  securitySchemes:
    apiKey:
      type: http
      scheme: bearer
      bearerFormat: if_live_ platform API key
      description: 'A platform API key minted in the portal (Warden). Its scopes are its

        permissions - `rig:read`, `rig:write`, `rig:run`,

        `rig:connector`, or `rig:*` - and it acts only in the organisation

        it was minted for. Keys without Rig scopes are refused with 403.

        '
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: Warden JWT
      description: 'A Warden user token. Each route also requires a tenant permission in

        the acting tenant (`X-Ironfang-Tenant`), resolved live from Warden:

        reads need `rig.read`; creating and revising projects and suites

        `rig.write`; starting, finishing and cancelling runs and allocating

        resources `rig.run`. A missing permission is 403; a permission

        lookup failure is 503.

        '
externalDocs:
  description: Ironfang Rig documentation
  url: https://ironfang.com/rig/docs