openapi: "3.0.1"
info:
  title: "Task API"
  description: |2-

        The Task API provides the ability to execute computation tasks in Evo that require variable, on-demand
        processing power. Building the Task API into your application can enable fast processing of long
        running, or resource intensive operations, without depending on the end user's physical hardware.

        Tasks are created, triggering a job to be executed asynchronously within a specific topic for your organization,
        and can be monitored throughout their execution lifecycle.

        For more information on using the Task API, see [Overview](/docs/guides/tasks), or the API
        references here.
  version: "0.0.2"
paths:
  /compute/orgs/{org_id}/{topic}/{task}:
    parameters:
      - $ref: "#/components/parameters/orgIdParam"
      - $ref: "#/components/parameters/topicParam"
      - $ref: "#/components/parameters/taskParam"
    post:
      tags:
        - Tasks
      summary: Trigger an asynchronous execution of a task
      description: "Trigger an asynchronous task within a specific topic for a designated organization. The task, topic, and organization ID are supplied as path parameters. A JSON request body, referencing the **ExecuteTaskRequest** schema and containing task-specific parameters, is required for this operation. Upon successful start, a 303 response is returned. The URL of the status endpoint for the newly created job is indicated in the Location header of the response."
      operationId: executeTask
      requestBody:
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/ExecuteTaskRequest"
      responses:
        "303":
          description: "303 response"
          headers:
            Location:
              description: The URL of the status endpoint for the newly created job
              schema:
                type: "string"
                format: "uri"
        "400":
          $ref: "#/components/responses/BadRequest"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "422":
          $ref: "#/components/responses/ValidationError"
        "429":
          $ref: "#/components/responses/TooManyRequest"
      security:
        - HTTPBearer: []
  /compute/orgs/{org_id}/{topic}/{task}/{job_id}:
    parameters:
      - $ref: "#/components/parameters/orgIdParam"
      - $ref: "#/components/parameters/topicParam"
      - $ref: "#/components/parameters/taskParam"
      - $ref: "#/components/parameters/jobIdParam"
    get:
      tags:
        - Jobs
      summary: Retrieve the results of a specific job
      description: "Gets the results of a specific job, identified by the organization ID, topic, task, and job ID. The job's status is returned in the response, along with either the results or an error object, depending on the status of the job. If the job is ongoing, the response includes links to the job's cancellation endpoint and detailed status endpoint."
      operationId: getJobResults
      responses:
        "200":
          description: The response for a completed job, which includes the job's status and may also contain either results or an error object, depending on the status of the job.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/CompletedJobResponse"
        "202":
          description: The response for an ongoing job, which includes the job's status and a links to the job's cancellation endpoint and detailed status endpoint.
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/OngoingJobResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequest"
      security:
        - HTTPBearer: []
    delete:
      tags:
        - Jobs
      summary: Cancel a specific job
      description: "Cancels a specific job, identified by the organization ID, topic, task, and job ID. The job's status is updated to 'canceling' and the job is stopped."
      operationId: cancelJob
      responses:
        "204":
          description: "204 response"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequest"
      security:
        - HTTPBearer: []
  /compute/orgs/{org_id}/{topic}/{task}/{job_id}/status:
    parameters:
      - $ref: "#/components/parameters/orgIdParam"
      - $ref: "#/components/parameters/topicParam"
      - $ref: "#/components/parameters/taskParam"
      - $ref: "#/components/parameters/jobIdParam"
    get:
      tags:
        - Jobs
      summary: Retrieve the status of a specific job
      description: "Gets the status of a specific job, identified by the organization ID, topic, task, and job ID. The job's status is returned in the response, along with a progress indicator, a message, and an error object, if applicable. If the job is ongoing, the response includes links to the job's cancellation endpoint."
      operationId: getJobStatus
      responses:
        "200":
          description: "200 response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobStatusResponse"
        "202":
          description: "202 response"
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobStatusResponse"
        "401":
          $ref: "#/components/responses/Unauthorized"
        "403":
          $ref: "#/components/responses/Forbidden"
        "404":
          $ref: "#/components/responses/NotFound"
        "429":
          $ref: "#/components/responses/TooManyRequest"
      security:
        - HTTPBearer: []
components:
  responses:
    BadRequest:
      description: The request could not be processed due to invalid syntax, malformed or missing required parameters
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    NotFound:
      description: The specified resource was not found
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Unauthorized:
      description: Unauthorized
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    Forbidden:
      description: Forbidden
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    ValidationError:
      description: Validation error
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
    TooManyRequest:
      description: API gateway rate limit exceeded
      content:
        application/json:
          schema:
            $ref: "#/components/schemas/Error"
  parameters:
    orgIdParam:
      name: "org_id"
      in: "path"
      required: true
      schema:
        type: "string"
        format: "uuid"
        pattern: "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
      description: "The organization identifier"
    topicParam:
      name: "topic"
      in: "path"
      required: true
      schema:
        type: "string"
      description: "The compute topic"
    taskParam:
      name: "task"
      in: "path"
      required: true
      schema:
        type: "string"
      description: "The compute task"
    jobIdParam:
      name: "job_id"
      in: "path"
      required: true
      schema:
        type: "string"
        format: "uuid"
        pattern: "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$"
      description: "The job identifier"
  schemas:
    JobStatusCompleted:
      type: "string"
      enum:
        - failed
        - canceled
        - succeeded
    JobStatusOngoing:
      type: "string"
      enum:
        - requested
        - in progress
        - canceling
    JobStatusEnum:
      type: "string"
      enum:
        - failed
        - canceled
        - succeeded
        - requested
        - in progress
        - canceling
    CompletedJobLinks:
      type: "object"
      properties:
        result:
          type: "string"
      required:
        - "result"
    OngoingJobLinks:
      type: "object"
      properties:
        cancel:
          type: "string"
      required:
        - "cancel"
    ExecuteTaskRequest:
      type: "object"
      properties:
        parameters:
          type: "object"
          additionalProperties: true
          title: Parameters
      required:
        - "parameters"
      title: ExecuteTaskRequest
    JobStatusResponse:
      type: "object"
      properties:
        status:
          allOf:
            - $ref: "#/components/schemas/JobStatusEnum"
        progress:
          type: "integer"
        message:
          type: "string"
        error:
          $ref: "#/components/schemas/Error"
        links:
          oneOf:
            - $ref: "#/components/schemas/CompletedJobLinks"
            - $ref: "#/components/schemas/OngoingJobLinks"

      required:
        - status
        - links
    CompletedJobResponse:
      type: "object"
      properties:
        status:
          allOf:
            - $ref: "#/components/schemas/JobStatusCompleted"
        results:
          type: "object"
        error:
          $ref: "#/components/schemas/Error"
      required:
        - status
    OngoingJobResponse:
      type: "object"
      properties:
        status:
          allOf:
            - $ref: "#/components/schemas/JobStatusOngoing"
      required:
        - status
    Error:
      properties:
        status:
          type: integer
        type:
          type: string
        title:
          type: string
        detail:
          type: string
      additionalProperties: true
      required:
        - status
        - type
        - title
      title: ErrorResponse
      type: object
  securitySchemes:
    HTTPBearer:
      type: http
      scheme: bearer
      bearerFormat: JWT
tags:
  - name: Tasks
    description: Operations for triggering tasks for a designated organization

  - name: Jobs
    description: Endpoints for retrieving and managing specific jobs
