Okareo Projects API

openapi: 3.2.0
info:
  title: Okareo Projects API
  version: 0.1.0
  description: Create and manage Projects.
servers:
- url: https://api.okareo.com
tags:
- name: Projects
  description: Create and manage Projects.
paths:
  /v0/projects:
    post:
      tags:
      - Projects
      summary: Create Project
      description: 'Create a project


        Returns:

        the id, name, and tags for the created project'
      operationId: create_project_v0_projects_post
      parameters:
      - name: api-key
        in: header
        required: true
        schema:
          type: string
          title: Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectSchema'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectResponse'
        '400':
          description: Input data is incorrect
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Okareo API token has failed authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Data is not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Input data is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    get:
      tags:
      - Projects
      summary: Get All Projects
      description: 'Get a list of projects for this organization


        Returns:

        a list of requested projects'
      operationId: get_all_projects_v0_projects_get
      parameters:
      - name: include_counts
        in: query
        required: false
        schema:
          type: boolean
          description: 'Also return how many Scenarios, Simulations, and Evaluations each project holds. Off by default: the counts aggregate over whole tables and this route is on the app''s boot path.'
          default: false
          title: Include Counts
        description: 'Also return how many Scenarios, Simulations, and Evaluations each project holds. Off by default: the counts aggregate over whole tables and this route is on the app''s boot path.'
      - name: api-key
        in: header
        required: true
        schema:
          type: string
          title: Api-Key
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/ProjectResponse'
                title: Response Get All Projects V0 Projects Get
        '400':
          description: Input data is incorrect
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Okareo API token has failed authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Data is not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Input data is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v0/projects/{project_id}:
    get:
      tags:
      - Projects
      summary: Get Project
      description: 'Get a project


        Returns:

        the requested project'
      operationId: get_project_v0_projects__project_id__get
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          description: The ID of the project
          title: Project Id
        description: The ID of the project
      - name: api-key
        in: header
        required: true
        schema:
          type: string
          title: Api-Key
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectResponse'
        '400':
          description: Input data is incorrect
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Okareo API token has failed authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Data is not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Input data is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    put:
      tags:
      - Projects
      summary: Update Project
      description: 'Update a project


        Returns:

        the requested project'
      operationId: update_project_v0_projects__project_id__put
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          description: ID of the project
          title: Project Id
        description: ID of the project
      - name: api-key
        in: header
        required: true
        schema:
          type: string
          title: Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectSchema'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectResponse'
        '400':
          description: Input data is incorrect
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Okareo API token has failed authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Data is not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Input data is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
    patch:
      tags:
      - Projects
      summary: Patch Project
      description: 'Partially update a project: name, tags and/or archive state.


        Only the fields present in the request body are applied. Archived projects

        stay fully usable; they are only hidden from the project picker.


        Returns:

        the updated project'
      operationId: patch_project_v0_projects__project_id__patch
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          description: ID of the project
          title: Project Id
        description: ID of the project
      - name: api-key
        in: header
        required: true
        schema:
          type: string
          title: Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectPatchSchema'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectResponse'
        '400':
          description: Input data is incorrect
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Okareo API token has failed authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Data is not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Input data is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v0/projects/{project_id}/clone:
    post:
      tags:
      - Projects
      summary: Clone Project
      description: 'Clones the Project: a new Project with the given name receives a copy of

        every Scenario (and its rows) in the source. Runs and their results,

        dashboards, and monitors are not copied; Targets, Drivers, and Checks are

        org-shared and visible from every Project, so there is nothing to copy.

        An archived source Project is clonable.


        The clone runs in one bounded transaction: it either completes whole or

        rolls back whole.'
      operationId: clone_project_v0_projects__project_id__clone_post
      parameters:
      - name: project_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          description: The ID of the source Project to clone
          title: Project Id
        description: The ID of the source Project to clone
      - name: dry_run
        in: query
        required: false
        schema:
          type: boolean
          description: Report what the clone would create — per-table row counts, the Scenario list, and blockers such as a destination name collision — without writing anything.
          default: false
          title: Dry Run
        description: Report what the clone would create — per-table row counts, the Scenario list, and blockers such as a destination name collision — without writing anything.
      - name: api-key
        in: header
        required: true
        schema:
          type: string
          title: Api-Key
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectCloneRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectClonePlan'
        '400':
          description: Input data is incorrect
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Okareo API token has failed authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Data is not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Input data is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: The clone is blocked (the new name collides with an existing Project, or is reserved). The detail is the full clone plan.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProjectCloneConflict'
        '500':
          description: The clone failed unexpectedly and was rolled back whole; nothing was created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: The clone transaction hit its lock/statement timeout and was rolled back whole; retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
  /v0/onboarding_status:
    put:
      tags:
      - Projects
      summary: Update Onboarding Status
      description: 'Update the onboarding completion status for the organization


        Args:

        status (str): The new onboarding completion status


        Returns:

        str: The updated onboarding completion status'
      operationId: update_onboarding_status_v0_onboarding_status_put
      parameters:
      - name: status
        in: query
        required: true
        schema:
          type: string
          title: Status
      - name: api-key
        in: header
        required: true
        schema:
          type: string
          title: Api-Key
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                type: string
                title: Response Update Onboarding Status V0 Onboarding Status Put
        '400':
          description: Input data is incorrect
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Okareo API token has failed authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Data is not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Input data is invalid
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ErrorResponse:
      properties:
        detail:
          type: string
          title: Detail
      type: object
      required:
      - detail
      title: ErrorResponse
    ProjectClonePlan:
      properties:
        source_project_id:
          type: string
          format: uuid
          title: Source Project Id
        source_project_name:
          type: string
          title: Source Project Name
        new_project_name:
          type: string
          title: New Project Name
        destination_project_id:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Destination Project Id
          description: ID of the created Project — set only after a clone that ran
        counts:
          $ref: '#/components/schemas/ProjectCloneCounts'
        scenarios:
          items:
            $ref: '#/components/schemas/ProjectCloneScenario'
          type: array
          title: Scenarios
          default: []
        blockers:
          items:
            $ref: '#/components/schemas/ProjectCloneBlocker'
          type: array
          title: Blockers
          default: []
        executed:
          type: boolean
          title: Executed
          description: True only on the response of a clone that actually ran
          default: false
      type: object
      required:
      - source_project_id
      - source_project_name
      - new_project_name
      - counts
      title: ProjectClonePlan
      description: What a Project clone will do (dry run / 409 detail) or did (executed).
    ProjectCloneScenario:
      properties:
        name:
          type: string
          title: Name
        row_count:
          type: integer
          title: Row Count
      type: object
      required:
      - name
      - row_count
      title: ProjectCloneScenario
    ProjectCloneConflict:
      properties:
        detail:
          $ref: '#/components/schemas/ProjectClonePlan'
      type: object
      required:
      - detail
      title: ProjectCloneConflict
      description: '409 body: the same plan payload, as HTTPException detail.'
    ProjectCloneRequest:
      properties:
        new_project_name:
          type: string
          minLength: 1
          title: New Project Name
          description: Name for the cloned Project. Surrounding whitespace is stripped; a name that is empty after stripping is refused (422).
      type: object
      required:
      - new_project_name
      title: ProjectCloneRequest
    ProjectSchema:
      properties:
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
          description: Name of the project
        tags:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Tags
          description: Tags are strings that can be used to filter projects in the Okareo app
          default: []
      type: object
      title: ProjectSchema
    ProjectPatchSchema:
      properties:
        name:
          anyOf:
          - type: string
          - type: 'null'
          title: Name
          description: Name of the project
        tags:
          anyOf:
          - items:
              type: string
            type: array
          - type: 'null'
          title: Tags
          description: Tags are strings that can be used to filter projects in the Okareo app
        is_archived:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Is Archived
          description: Archive state. Archived projects are hidden from the project picker but remain fully usable.
      type: object
      title: ProjectPatchSchema
      description: 'Partial update — only the keys the caller actually sent are applied

        (`model_dump(exclude_unset=True)`); an explicit null is refused (400), it is

        not a valid value for any of these fields.'
    ProjectCloneBlocker:
      properties:
        code:
          type: string
          enum:
          - destination_name_collision
          - destination_name_reserved
          title: Code
        detail:
          type: string
          title: Detail
          description: Human-readable reason, rendered verbatim
      type: object
      required:
      - code
      - detail
      title: ProjectCloneBlocker
    ProjectCloneCounts:
      properties:
        project:
          type: integer
          title: Project
          default: 1
        scenario_set:
          type: integer
          title: Scenario Set
          default: 0
        scenario_data_point:
          type: integer
          title: Scenario Data Point
          default: 0
      type: object
      title: ProjectCloneCounts
      description: Rows the clone creates, per table.
    ProjectResponse:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        name:
          type: string
          title: Name
        tags:
          items:
            type: string
          type: array
          title: Tags
          default: []
        is_archived:
          type: boolean
          title: Is Archived
          default: false
        onboarding_status:
          type: string
          title: Onboarding Status
        time_created:
          type: string
          format: date-time
          title: Time Created
        scenario_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Scenario Count
          description: Scenarios in this project. Requires include_counts.
        simulation_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Simulation Count
          description: Runs of type MULTI_TURN in this project. Requires include_counts.
        evaluation_count:
          anyOf:
          - type: integer
          - type: 'null'
          title: Evaluation Count
          description: Runs of every type other than MULTI_TURN in this project. Requires include_counts.
      type: object
      required:
      - id
      - name
      - onboarding_status
      - time_created
      title: ProjectResponse