> For the complete documentation index, see [llms.txt](https://docs.annolab.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.annolab.ai/projects-directories-and-sources/source-files.md).

# Source Files

## Retrieve source information

<mark style="color:blue;">`GET`</mark> `https://api.annolab.ai/v1/source/{source_id}`

Returns basic source information, including a signed URL to download the original file and its tags.

#### Query Parameters

| Name                                         | Type | Description      |
| -------------------------------------------- | ---- | ---------------- |
| source\_id<mark style="color:red;">\*</mark> | Int  | Id of the source |

#### Headers

| Name                                            | Type   | Description                                                                              |
| ----------------------------------------------- | ------ | ---------------------------------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | <p>Your API key<br><code>{"Authorization": "Api-Key XXXXXXX-XXXXXXX-XXXXXXX"}</code></p> |

{% tabs %}
{% tab title="200: OK " %}

{% endtab %}
{% endtabs %}

```json
// Example Response
{
    "id": 2,
    "projectName": "My Project",
    "projectId": 1,
    "directoryName": "Uploads",
    "directoryId": 1,
    "name": "REGISTRATION.pdf",
    "sourceName": "REGISTRATION.pdf",
    "type": "pdf",
    "text": "Example PDF Text",
    "url": "https://download-example-url.pdf",
    "createdAt": "2023-05-22T20:32:02.633Z",
    "tags": [
        {
            "domainEntityId": 1,
            "typeName": "Airframe Inventory",
            "attributes": [
                {
                    "name": "Make",
                    "value": "CESSNA"
                },
                {
                    "name": "Model",
                    "value": "421C"
                },
                {
                    "name": "Serial Number",
                    "value": "421C-5837"
                }
            ],
            "createdBy": {
                "id": 58473,
                "email": "testuser@gmail.com",
                "username": "testuser"
            }
        }
    ]
}
```

## Upload a PDF

<mark style="color:green;">`POST`</mark> `https://api.annolab.ai/v1/source/upload-pdf`

Upload a PDF and specify an OCR method to apply. (optional) invoke a workflow of AI models

#### Headers

| Name                                            | Type   | Description                                                                                                                                                           |
| ----------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | String | <p>Where you put your api key. Creating a directory requires a key with "Write" permissions.<br><code>{"Authorization": "Api-Key XXXXXXX-XXXXXXX-XXXXXXX"}</code></p> |

#### Request Body

| Name                                                | Type            | Description                                                                                                                                        |
| --------------------------------------------------- | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| projectIdentifier<mark style="color:red;">\*</mark> | string\|number  | Either id of the project or name of the project where file will reside                                                                             |
| directoryIdentifier                                 | string          | name of the directory where the file will reside                                                                                                   |
| sourceIdentifier<mark style="color:red;">\*</mark>  | string          | Name of the source that will be created                                                                                                            |
| ocrProvider                                         | string          | Only used if processMode is set to OCR. Valid values are "textract", "textract\_plus", and "gcv". "textract\_plus" recommended for highest quality |
| preprocessor                                        | string          | Valid options are "faa" and None.                                                                                                                  |
| groupName<mark style="color:red;">\*</mark>         | string          | Name of the group that owns the project                                                                                                            |
| tags                                                | CanonicalTag\[] | Array of [CanonicalTag](/annotations-and-relations/canonical-tags.md#canonicaltag-object) objects                                                  |
| workflow                                            | string          | Workflow (aka package of AI models) that will be invoked immediately after upload. Recommend "FAA\_CD\_WITH\_VLM" or "FAA\_CD\_WITH\_TAGGING"      |
| processMode                                         | string          | Use "OCR" if the pdf is not already text enriched. Use "EXTRACT" if pdf already has text embedded                                                  |

{% tabs %}
{% tab title="Python" %}

```python
import os
import json
import requests

ANNO_LAB_API_KEY = 'XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX'

url_base = 'https://api.annolab.ai'

input_pdf = '/Users/grantdelozier/devel/ocr-these3/TEST-REGISTRATION.PDF'

headers = {
  'Authorization': 'Api-Key '+ANNO_LAB_API_KEY,
}

url = url_base+'/v1/source/create-pdf'

requestBody = {
  'groupName': 'AnnoLab',
  'projectIdentifier': 'title-demo',
  'directoryIdentifier': 'testing',
  'sourceIdentifier': 'TEST-REGISTRATION.PDF',
  'preprocessor': 'faa',
  'processMode': 'OCR',
  'ocrProvider': 'textract_plus',
  'workflow': 'FAA_CD'
}

fileToUpload = {
  'file': ('TEST-REGISTRATION.PDF', open(input_pdf, 'rb'), 'application/pdf')
}

url = url_base+'/v1/source/upload-pdf'

response = requests.post(url, headers=headers, data=requestBody, files=fileToUpload)
print(response.json())

```

{% endtab %}
{% endtabs %}

## Create Source Text

<mark style="color:green;">`POST`</mark> `https://api.annolab.ai/v1/source/create-text`

Create a new text file source within a directory.

#### Headers

| Name                                            | Type   | Description                                                                                                                                                           |
| ----------------------------------------------- | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization<mark style="color:red;">\*</mark> | string | <p>Where you put your api key. Creating a directory requires a key with "Write" permissions.<br><code>{"Authorization": "Api-Key XXXXXXX-XXXXXXX-XXXXXXX"}</code></p> |

#### Request Body

| Name                | Type   | Description                                                                                      |
| ------------------- | ------ | ------------------------------------------------------------------------------------------------ |
| projectIdentifier   | string | Identifier for the project that will contain the source file. Either the id or the unique name   |
| directoryIdentifier | string | Identifier for the directory that will contain the source file. Either the id or the unique name |
| sourceName          | string | Name of the file you wish to create                                                              |
| text                | string | Text that exists within the file                                                                 |

{% tabs %}
{% tab title="201 Source text was successfully created" %}

```
{
    "sourceName": "athens.txt,
    "directoryName": "Wikipedia Subset",
    "directoryId": 12,
    "projectName": "New NER Project",
    "projectId": 22,
    "id": 145
}
```

{% endtab %}
{% endtabs %}

This code shows how to create a new text file source

{% tabs %}
{% tab title="Python" %}

```python
import requests

ANNO_LAB_API_KEY = 'XXXXXXX-XXXXXXX-XXXXXXX-XXXXXXX'

source = {
  'projectIdentifier': 'New NER Project',
  'directoryIdentifier': 'Wikipedia Subset',
  'sourceName': 'athens.txt'
  'text': 'Athens (Greek: Αθήνα, Athína), is the capital city of Greece with a metropolitan population of 3.7 million inhabitants.'
}

headers = {
  'Authorization': 'Api-Key '+ANNO_LAB_API_KEY,
}

url = 'https://api.annolab.ai/v1/source/create-text'

response = requests.post(url, headers=headers, json=source)

print(response.json())
```

{% endtab %}
{% endtabs %}