Skip to content

API Documentation

Overview

This API provides functionalities for user authentication and codon usage optimization. Some endpoints require authentication using an access token obtained after login.

Endpoints

1. API Status (/)

Method: GET

Description: Returns the status of the API, indicating whether the service is running.

Authentication: ❌ Not required

Response Example: 

{
  "build": "5bae0bac9ae07cf515b1cd0687a6861c778b6601",
  "environment": "prod",
  "firebase": true
}

Output Parameters

  • build: The SHA-1 hash defining the version build of the API.
  • environment: The environment of the API
  • firebase: The status of the internal database

2. User Login (/login)

Method: POST

Description: Authenticates the user and returns an access token. The access token is valid for 60 minutes. Then it needs to be regenerated.

Authentication: ❌ Not required

Query Parameters:

  • username (string, required): Username
  • password (string, required): User password

Response Example: 

{
  "token": "your_generated_token"
}

Output Parameters - token: The access token to be used for querying the API when authentication is required.

3. Sequence optimization (/optimise)

Method: POST

Description:
This endpoint creates a new sequence optimisation job to be added to the queue. The API will process the job as soon as a worker is available. It requires authentication via a bearer token. You must provide a unique name identifier and the sequence payload, alongside a list of fitnesses to be used for the optimization process.

The sequence can be submitted in two formats: as a standard continuous string, or as an array of component objects representing different functional regions. When using the array format, exactly one component must be designated as the "gene_of_interest".

Each fitness metric might require a specific set of parameters that need to be provided in this API call. Each fitness accepts an additional parameter weight that specifies the relative importance of that metric. If no weight is provided, 1.0 is assumed. The method returns a job identifier that can be used to check the job status and to retrieve the results.

Authentication: ✅ Required

Headers: - Authorization: Bearer <access_token>

Request Body Parameters:

  • sequence (string | array of objects): The nucleotide sequence to optimise.
  • If a string: Represents the continuous coding sequence.
  • If an array: An ordered list of sequence components. Each object must contain a sequence (string) and a featureType (string). The array must contain exactly one component where featureType is "gene_of_interest".
  • 5_utr (string, optional): The 5'UTR sequence associated with the coding sequence. Note: This parameter is ignored if the sequence is provided as a list of components.
  • 3_utr (string, optional): The 3'UTR sequence associated with the coding sequence. Note: This parameter is ignored if the sequence is provided as a list of components.
  • name (string): The unique identifier for the sequence, used for tracking and reporting purposes.
  • fitness_list (array of objects): A list of fitness metrics to be used for the optimization. Fitness parameters are individually defined in the fitness page.

Request Body Example 1 (String Format): 

{
  "sequence": "ATGCGTACGTA",
  "5_utr": "GGATCGAT",
  "3_utr": "AAAAAAAA",
  "name": "sequence_id",
  "fitness_list": [
    {
        "name": "dna_manufact",
        "weight": 1.0
    },
    {
        "name": "gc_content",
        "min": 35.0,
        "max": 60.0,
        "weight": 1.0
    }
  ]
}

Request Body Example 2 (Component Array Format): 

{
  "name": "complex_sequence_id",
  "sequence": [
    {
      "sequence": "TATAAA",
      "featureType": "promoter"
    },
    {
      "sequence": "ATGCGTACGTA",
      "featureType": "gene_of_interest"
    },
    {
      "sequence": "AAAAAA",
      "featureType": "poly_a_tail"
    }
  ],
  "fitness_list": [
    {
        "name": "dna_manufact",
        "weight": 1.0
    }
  ]
}

Response Example: 

{
  "name": "sequence_id",
  "jobid": "123e4567-e89b-12d3-a456-426614174000"
}

Output Parameters

  • name: The unique identifier for the sequence, used for tracking and reporting purposes.
  • jobid: The uuid representing the submitted job.

4. Job status (/optimise/status)

Method: POST

Description: Returns the status of one or more submitted jobs.

Authentication: ✅ Required

Headers: - Authorization: Bearer <access_token>

Request Body (JSON): 

{
  "jobids": [
    "123e4567-e89b-12d3-a456-426614174000",
    "987e6543-e21b-45d3-b789-123456789abc"
  ]
}

Notes

  • jobids must be an array
  • Minimum length: 1
  • Each element must be a valid UUID

Response Example: 

{
  "results": [
    {
      "jobid": "123e4567-e89b-12d3-a456-426614174000",
      "status": "pending"
    },
    {
      "jobid": "987e6543-e21b-45d3-b789-123456789abc",
      "status": "running"
    }
  ]
}

Output Parameters

  • results: Array of job status objects
    • jobid: The uuid representing the submitted job.
    • status: The job status. It can be one of the following: pending, processing, error, success

5. Job result (/optimise/result)

Method: POST

Description: Returns the result of a given optimisation job.

Authentication: ✅ Required

Headers: - Authorization: Bearer <access_token>

Request Body (JSON): 

{
  "jobid": "123e4567-e89b-12d3-a456-426614174000"
}

Response Example: 

{
  "jobid": "123e4567-e89b-12d3-a456-426614174000",
  "status": "success",
  "results": [
    {
      "type": "original",
      "sequence": "ATGCTAGCTAGC",
      "score": 8.2,
      "motif_in_cds": 0,
      "motif_in_utr": 0,
      "fitness_list": [
        { "name": "dna_manufact", "weight": 1.0, "score": 0.50 },
        { "name": "gc_content", "weight": 1.0, "score": 3.70 },
        { "name": "cai", "weight": 1.0, "score": 4.00 }
      ]
    },
    {
      "type": "optimized",
      "sequence": "ATCCTTGCTAGC",
      "score": 13.6,
      "motif_in_cds": 0,
      "motif_in_utr": 0,
      "fitness_list": [
        { "name": "dna_manufact", "weight": 1.0, "score": 1.24 },
        { "name": "gc_content", "weight": 1.0, "score": 1.00 },
        { "name": "cai", "weight": 1.0, "score": 5.00 }
      ]
    },
    {
      "type": "optimized",
      "sequence": "ATCCTTGTTAGC",
      "score": 13.2,
      "motif_in_cds": 0,
      "motif_in_utr": 0,
      "fitness_list": [
        { "name": "dna_manufact", "weight": 1.0, "score": 1.24 },
        { "name": "gc_content", "weight": 1.0, "score": 1.00 },
        { "name": "cai", "weight": 1.0, "score": 5.01 }
      ]
    },
    {
      "type": "optimized",
      "sequence": "ATCCTTGATAGC",
      "score": 11.6,
      "motif_in_cds": 0,
      "motif_in_utr": 0,
      "fitness_list": [
        { "name": "dna_manufact", "weight": 1.0, "score": 1.25 },
        { "name": "gc_content", "weight": 1.0, "score": 1.00 },
        { "name": "cai", "weight": 1.0, "score": 5.30 }
      ]
    }
  ]
}

Output Parameters

  • jobid: The uuid representing the submitted job.
  • status: The job status. It can be one of the following: pending, running, error, success.
  • results: An ordered array of sequence objects evaluated by the genetic algorithm. The endpoint returns the original sequence, plus the three best sequences resulting from the optimization
  • type: Indicates the origin of the sequence. original represents the baseline input provided by the user (strictly returned at index 0). optimised represents an algorithmically evolved candidate.
  • sequence: The specific nucleotide sequence string.
  • score: The overall mathematically calculated score for this sequence, accounting for all weighted fitness metrics.
  • fitness_list: The detailed breakdown of individual fitness metrics for this sequence, containing the name, the applied weight, and the individual computed score.
  • motif_in_cds: The number of known forbidden motifs in the CDS.
  • motif_in_utr: The number of known forbidden motifs in the UTRs.

6. Fitness list (/fitness)

Method: GET

Description: Returns a list of available fitness for optimization.

Authentication: ❌ Not required

Response Example: 

{
  "fitness_functions": [
    {
      "id": "cai",
      "name": "Codon Adaptation Index",
      "parameters": [
        {
          "name": "weight",
          "required": false,
          "type": "number"
        }
      ]
    },
    {
      "id": "dna_manufact",
      "name": "DNA Manufacturability",
      "parameters": [
        {
          "name": "weight",
          "required": false,
          "type": "number"
        }
      ]
    },
    {
      "id": "ppy",
      "name": "Pseudoyield",
      "parameters": [
        {
          "name": "weight",
          "required": false,
          "type": "number"
        }
      ]
    },
    {
      "id": "u_content",
      "name": "Uridine Content",
      "parameters": [
        {
          "name": "weight",
          "required": false,
          "type": "number"
        }
      ]
    }
  ]
}

Output Parameters

  • id: The unique id of the fitness to be used for optimization requests.
  • name: A descriptive name for the fitness.
  • parameters: The list of parameters.
    • name: The name of a specific parameter
    • required: A boolean defining the required parameters
    • type: The variable type. It can be one of the following: boolean, number, integer, string

7. Fitness details (/fitness/<id>)

Method: GET

Description: Returns details for a specific fitness.

Authentication: ❌ Not required

Response Example: 

{
  "id": "cai",
  "name": "Codon Adaptation Index",
  "parameters": [
    {
      "name": "weight",
      "required": false,
      "type": "number"
    }
  ]
}

Output Parameters

  • id: The unique id of the fitness to be used for optimization requests.
  • name: A descriptive name for the fitness.
  • parameters: The list of parameters.
    • name: The name of a specific parameter
    • required: A boolean defining the required parameters
    • type: The variable type. It can be one of the following: boolean, number, integer, string

8. Job List (/jobs)

Method: GET

Description: Returns a paginated list of sequence optimization jobs submitted by the authenticated user.

Authentication: ✅ Required

Headers: - Authorization: Bearer <access_token>

Query Parameters

  • limit (integer, optional): The number of jobs to return per page. Defaults to 10.
  • start (string, optional): The job_id cursor to start pagination from.

Response Example: 

{
  "jobs": [
    {
      "jobid": "123e4567-e89b-12d3-a456-426614174000",
      "name": "sequence_id_1",
      "status": "success",
      "created_at": "2026-05-11T12:00:00.000000"
    },
    {
      "jobid": "987e6543-e21b-45d3-b789-123456789abc",
      "name": "sequence_id_2",
      "status": "pending",
      "created_at": "pending"
    }
  ],
  "next": "987e6543-e21b-45d3-b789-123456789abc",
  "previous": null
}

Output Parameters

  • jobs: An array containing basic information for the requested jobs.
    • jobid: The unique identifier representing the submitted job.
    • name: The unique identifier/name for the sequence provided upon submission.
    • status: The current processing status of the job (e.g., pending, running, error, success).
    • created_at: An ISO-formatted timestamp string of when the job was created. Evaluates to "pending" if the job has not yet been processed by the database sentinel.
  • next: The job_id string to use as the start parameter for fetching the next page of results. null if there are no further pages.
  • previous: The job_id string to use as the start parameter for fetching the previous page of results. null if on the first page.

9. Job Details (/jobs/)

Method: GET

Description: Retrieves the complete data payload for a specific job ID submitted by the authenticated user.

Authentication: ✅ Required

Headers: - Authorization: Bearer <access_token>

Query Parameters

  • jobid: The unique identifier representing the submitted job.

Response Example: 

{
  "jobid": "123e4567-e89b-12d3-a456-426614174000",
  "name": "sequence_id",
  "status": "success",
  "created_at": "2026-05-11T12:00:00.000000",
  "sequence": "ATGCGTACGTA",
  "payload": ["..."],
  "results": [
      "... (nested algorithmic results) ..."
  ]
}

Output Parameters

  • jobid: The unique identifier representing the job.
  • name: The user-defined name for the sequence.
  • status: The current status of the job (e.g., pending, running, error, success).
  • created_at: An ISO-formatted timestamp string of job creation, or "pending" if not yet finalized by the database.
  • payload: The optimization payload
  • results: The optimization result. Please refer to /optimise/result for further details

Endpoint Summary

Endpoint Method Public Description
/ GET ✅ API status check
/login POST ✅ Authenticate and obtain an access token
/optimise POST ❌ Send sequence optimization job
/optimise/status POST ❌ Check job status
/optimise/result POST ❌ Returns optimization result
/fitness GET ✅ Returns a list of available fitness for optimization
/fitness/<id> GET ✅ Returns details for a specific fitness
/jobs GET ❌ Returns a paginated list of user jobs
/jobs/<id> GET ❌ Returns complete data for a specific job

Authentication

  • Endpoints marked as private require authentication.
  • Use the /login endpoint to obtain an access token.
  • Include the token in the Authorization header of your requests: 
    Authorization: Bearer your_access_token

This documentation is automatically updated with every repository commit via GitHub Actions.