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 avaiable. It requires authentication via a bearer token. You must provide both the sequence and a unique name identifier, together with a list of fitnesses to be used for the optimization process. Each fitness might require a specific set of parameters that needs to be provided in this API call. Additionally, you may include the optional parameters start and end to specify the coding sequence region. If these parameters are not provided, the entire sequence is used by default. The method returns a job identificator than can be used to check the job status and to retrieve the results. Each fitness accept an additional parameter weigth that specifies the relative importance of each fitness. If no weight is provided, 1.0 is assumed.

Authentication: ✅ Required

Headers: - Authorization: Bearer <access_token>

Output Parameters

  • sequence: The coding sequence to optimise.
  • 5_utr: The 5'UTR sequence associated to the coding sequence
  • 3_utr: The 3'UTR sequence associated to the coding sequence
  • name:
  • fitness_list: A list of fitnesses to be used for the optimization. Fitness parameters are individually defined in the fitness page

Request Body (JSON): 

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

Response Example: 

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

Output Parameters

  • name: The unique identifier for the sequence, used for tracking and reporting purposes.
  • sequence: The nucleotide sequence that was analyzed.
  • 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, running, 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": "pending",
  "sequence": "ATGCTAGCTAGC",
  "optimised": "ATCCTTGCTAGC",
  "score": 13.6,
  "fitness_list": [
    {
        "name": "rna_manufact",
        "weight": 1.0,
        "score": 1.24
    },
    {
        "name": "gc_content",
        "weight": 1.0,
        "score": 1.0
    },
    {
        "name": "te_ribonn",
        "weight": 1.0,
        "score": 5.0
    }
  ]
}

Output Parameters

  • jobid: The uuid representing the submitted job.
  • status: The job status. It can be one of the following: pending, running, error, success.
  • sequence: The input sequence
  • optimised: The optimised sequence
  • score: The overall score of the optimised sequence, accounting for all fitnesses.
  • fitness_list: The input list of fitnesses with the weight and the individual score.

Endpoint Summary

Endpoint Method Public Description
/ GET ✅ API status check
/login POST ✅ Authenticate and obtain an access token
/optimise POST ❌ Predict sequence manufacturability
/optimise/status POST ❌ Check job status
/optimise/result POST ❌ Returns optimization result

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.