Use the API to Retrieve Data

This appendix explains how to access your Codex Catalog data via the REST API.
You will:

1. Authenticate and obtain an access token.
2. Retrieve available lists.
3. Query data from a specific list.

---

1) Get an Access Token

Authenticate an API user and obtain a JWT token for subsequent requests.

Request

• Method: POST
• URL: https://<codex-catalog-host>/api/token/
• Headers:
  Content-Type: application/x-www-form-urlencoded
• Body (form):
  username=<api-user-name>&password=<api-user-password>

PythoncURL

import requests

url = "https://<codex-catalog-host>/api/token/"
data = {
    "username": "<api-user-name>",
    "password": "<api-user-password>"
}
headers = {"Content-Type": "application/x-www-form-urlencoded"}
resp = requests.post(url, data=data, headers=headers, timeout=30)
resp.raise_for_status()
print(resp.json())

curl --location 'https://<codex-catalog-host>/api/token/'       --header 'Content-Type: application/x-www-form-urlencoded'       --data-urlencode 'username=<api-user-name>'       --data-urlencode 'password=<api-user-password>'

Response (200)

{
  "refresh": "<refresh-token>",
  "access": "<access-token>"
}

---

2) Retrieve Available Lists

Use the access token to list all available lists in the Codex Catalog Catalog.

Request

• Method: GET
• URL: https://<codex-catalog-host>/api/v1/rest/list/
• Headers:
  Authorization: Token <access-token>

PythoncURL

import requests

url = "https://<codex-catalog-host>/server/api/v1/rest/list/"
headers = {"Authorization": "Token <access-token>"}
resp = requests.get(url, headers=headers, timeout=30)
resp.raise_for_status()
print(resp.json())

curl --location 'https://<codex-catalog-host>/server/server/api/v1/rest/list/'       --header 'Authorization: Token <access-token>'

Response (200)

{
  "data": [
    { "id": 340, "name": "Staff Directory" },
    { "id": 345, "name": "Import Types" },
    { "id": 322, "name": "Business Units" },
    { "id": 320, "name": "Countries (ISO-3166-1)" },
    { "id": 368, "name": "Events List" }
  ],
  "timestamp": "2025-10-10T12:16:18.601300Z"
}

The id field identifies each list.
You’ll use this value in the next step to query specific list data.

---

3) Retrieve Data from a List

Fetch paginated records for a specific list.

Request

• Method: POST
• URL: https://<codex-catalog-host>/api/v1/rest/list/
• Headers:
• Authorization: Token <access-token>
• Content-Type: application/json
• Body (JSON):
• list_id — the list’s numeric ID (from step 2)
• page — which page to retrieve
• page_size — number of records per page

PythoncURL

import requests
import json

url = "https://<codex-catalog-host>/server/api/v1/rest/list/"
payload = {
    "list_id": 320,
    "page": 1,
    "page_size": 5
}
headers = {
    "Authorization": "Token <access-token>",
    "Content-Type": "application/json"
}
resp = requests.post(url, headers=headers, data=json.dumps(payload), timeout=30)
resp.raise_for_status()
print(resp.json())

curl --location 'https://<codex-catalog-host>/server/api/v1/rest/list/'       --header 'Authorization: Token <access-token>'       --header 'Content-Type: application/json'       --data '{
    "list_id": 320,
    "page": 1,
    "page_size": 5
  }'

Response (200)

{
  "data": [
    {
      "lmsys_reviewed_by": null,
      "lmsys_approval_status": "Approved",
      "lmsys_approval_action": "U",
      "lmsys_related_id": null,
      "lmcol_country": "Aruba",
      "lmcol_alpha_3": "ABW",
      "lmcol_alpha_2": "AW",
      "lmcol_numeric": 533
    },
    {
      "lmsys_reviewed_by": null,
      "lmsys_approval_status": "Approved",
      "lmsys_approval_action": "U",
      "lmsys_related_id": null,
      "lmcol_country": "Afghanistan",
      "lmcol_alpha_3": "AFG",
      "lmcol_alpha_2": "AF",
      "lmcol_numeric": 4
    },
    {
      "lmsys_reviewed_by": null,
      "lmsys_approval_status": "Approved",
      "lmsys_approval_action": "U",
      "lmsys_related_id": null,
      "lmcol_country": "Angola",
      "lmcol_alpha_3": "AGO",
      "lmcol_alpha_2": "AO",
      "lmcol_numeric": 24
    },
    {
      "lmsys_reviewed_by": null,
      "lmsys_approval_status": "Approved",
      "lmsys_approval_action": "U",
      "lmsys_related_id": null,
      "lmcol_country": "Anguilla",
      "lmcol_alpha_3": "AIA",
      "lmcol_alpha_2": "AI",
      "lmcol_numeric": 660
    },
    {
      "lmsys_reviewed_by": null,
      "lmsys_approval_status": "Approved",
      "lmsys_approval_action": "U",
      "lmsys_related_id": null,
      "lmcol_country": "Åland Islands",
      "lmcol_alpha_3": "ALA",
      "lmcol_alpha_2": "AX",
      "lmcol_numeric": 248
    }
  ],
  "page": 1,
  "page_size": 5,
  "total_records": 252,
  "start": 0,
  "end": 5,
  "timestamp": "2025-10-10T13:08:44.118861Z"
}

Response Fields

Field	Description
data	Array of record objects.
lmsys_*	System columns used by Codex Catalog.
lmcol_*	Actual data columns from your list.
page, page_size	Pagination information.
total_records	Total number of records in the list.
start, end	Record index range for this page.
timestamp	Retrieval time in UTC.

---

Troubleshooting

Issue	Possible Cause	Fix
401 Unauthorized	Invalid or expired token.	Re-authenticate to get a new token.
404 Not Found	Wrong base path.	Make sure you use the right URL.