> For the complete documentation index, see [llms.txt](https://help.bioinsight.illumina.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.bioinsight.illumina.com/connected-analytics/api-access/getting-started/api-introduction.md).

# API Beginner Guide

## Converting curl to Python

The examples on the [API Reference](https://ica.illumina.com/ica/api/swagger/index.html) page use curl (Client URL) while Python uses Python requests. There are a number of online tools to automatically convert from curl to python.

To get the curl command,

1. Look up the endpoint you want to use on the API reference page.
2. Select `Try it out`.
3. Enter the necessary parameters.
4. Select `Execute`.
5. Copy the resulting curl command.

{% hint style="danger" %}
**Never paste your API authentication key into online tools when performing curl conversion as this poses a significant security risk.**
{% endhint %}

In the most basic form, the curl command

`curl my.curlcommand.com`

becomes

```python
import requests
response = requests.get('http://my.curlcommand.com')
```

You will see the following options in the curl commands on the [API Reference](https://ica.illumina.com/ica/api/swagger/index.html) page.

`-H` means header.

`-X` means the string is passed "as is" without interpretation.

```python
curl -X 'GET' 'https://my.curlcommand.com' -H 'HeaderName: HeaderValue'
```

becomes

```python
import requests
headers = {
    'HeaderName': 'HeaderValue',
}
response = requests.get('https://my.curlcommand.com', headers=headers)
```

## API Examples

### **Request a list of event codes**

This is a straightforward request without parameters which can be used to to verify your connection.

The API call is

{% code overflow="wrap" %}

```
response = requests.get('https://ica.illumina.com/ica/rest/api/eventcodes', headers={'X-API-Key': '<your_generated_API_key>'})
```

{% endcode %}

In this example, the API key is part of your API call, which means you must update all API calls when the key changes. A better practice is to put this API key in the headers so it is easier to maintain. The full code then becomes

{% code overflow="wrap" %}

```python
# The requests library will allow you to make HTTP requests.
import requests

# Replace <your_generated_API_key> with your actual generated API key here.
headers = {
    'X-API-Key': '<your_generated_API_key>',
}

# Store the API request in response.
response = requests.get('https://ica.illumina.com/ica/rest/api/eventCodes', headers=headers)

# Display the response status code. Code 200 means the request succeeded.
print("Response status code: ", response.status_code)

# Display the data from the request.
print(response.json())
```

{% endcode %}

### **Pretty-printing the result**

The list of application codes was returned as a single line, which makes it difficult to read, so let's pretty-print the result.

{% code overflow="wrap" %}

```python
# The requests library will allow you to make HTTP requests.
import requests

# JSON will allow us to format and interpret the output.
import json

# Replace <your_generated_API_key> with your actual generated API key here.
headers = {
    'X-API-Key': '<your_generated_API_key>',
}

# Store the API request in response.
response = requests.get('https://ica.illumina.com/ica/rest/api/eventCodes', headers=headers)

# Display the response status code. Code 200 means the request succeeded.
print("Response status code: ", response.status_code)

# Put the JSON data from the response in My_API_Data.
My_API_Data = response.json()

# Print JSON data in readable format with indentation and sorting.
print(json.dumps(My_API_Data, indent=3, sort_keys=True))
```

{% endcode %}

### **Retrieving a list of projects**

Now that we are able to retrieve information with the API, we can use it for a more practical request like retrieving a list of projects. This API request can also take parameters.

#### Retrieve all projects

First, we pass the request without parameters to retrieve all projects.

{% code overflow="wrap" %}

```python
# The requests library will allow you to make HTTP requests.
import requests

# JSON will allow us to format and interpret the output.
import json

# Replace <your_generated_API_key> with your actual generated API key here.
headers = {
    'X-API-Key': '<your_generated_API_key>',
}

# Store the API request in response.
response = requests.get('https://ica.illumina.com/ica/rest/api/projects', headers=headers)

# Display the response status code. Code 200 means the request succeeded.
print("Response status code: ", response.status_code)

# Put the JSON data from the response in My_API_Data.
My_API_Data = response.json()

# Print JSON data in readable format with indentation and sorting.
print(json.dumps(My_API_Data, indent=3, sort_keys=True))
```

{% endcode %}

#### Single parameter

The easiest way to pass a parameter is by appending it to the API request. The following API request will list the projects with a filter on CAT as user tag.

{% code overflow="wrap" %}

```python
response = requests.get('https://ica.illumina.com/ica/rest/api/projects?userTags=CAT', headers=headers)
```

{% endcode %}

#### Multiple parameters

If you only want entries that have both the tags CAT and WOLF, you would append them like this:

{% code overflow="wrap" %}

```python
response = requests.get('https://ica.illumina.com/ica/rest/api/projects?userTags=CAT&userTags=WOLF', headers=headers)
```

{% endcode %}

### **Copying Data**

To copy data, you need to know:

* Your generated **API key**.
* The dataId of the files and folders which you want to copy (their syntax is fil.hexadecimal\_identifier and fol.hexadecimal\_identifier). You can select a file or folder in the GUI and select it to see the Id (**Projects > your\_project > Data > your\_file > Data details > Id**) or you can use the `/api/projects/{projectId}/data` endpoint.
* The **destination project** to which you want to copy the data.
* The **destination folder** within the destination project to which you want to copy the data (fol.hexadecimal\_identifier).
* What to do when the destination files or folders already exist (OVERWRITE, SKIP or RENAME).

The full code will then be as follows:

{% code overflow="wrap" %}

```python
# The requests library will allow you to make HTTP requests.
import requests

# Fill out your generated API key.
headers = {
    'accept': 'application/vnd.illumina.v3+json',
    'X-API-Key': '<your_generated_API_key>',
    'Content-Type': 'application/vnd.illumina.v3+json',
}

# Enter the files and folders, the destination folder, and the action to perform when the destination data already exists.
data = '{"items": [{"dataId": "fil.0123456789abcdef"}, {"dataId": "fil.735040537abcdef"}], "destinationFolderId": "fol.1234567890abcdef", "copyUserTags": true,"copyTechnicalTags": true,"copyInstrumentInfo": true,"actionOnExist": "SKIP"}'

# Replace <Project_Identifier> with the actual identifier of the destination project.
response = requests.post(
    'https://ica.illumina.com/ica/rest/api/projects/**<Project_Identifier>**/dataCopyBatch',
    headers=headers,
    data=data,
)

# Display the response status code.
print("Response status code: ", response.status_code) 
```

{% endcode %}

Now that you can make individual API requests and work with responses, you can combine API calls into complete workflows. For an end-to-end example, see [Run a Pipeline](/connected-analytics/api-access/getting-started/api-introduction/run-a-pipeline.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.bioinsight.illumina.com/connected-analytics/api-access/getting-started/api-introduction.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.