### List API Versions using JavaScript (Fetch API)

Source: https://developers.catenda.com/list-api-versions

This example demonstrates how to list API versions using the Fetch API in JavaScript. It makes a GET request and logs the response or any errors.

```javascript
var myHeaders = new Headers();
myHeaders.append("Accept", "application/json");
myHeaders.append("Content-Type", "application/json");

var requestOptions = {
   method: 'GET',
   headers: myHeaders,
   redirect: 'follow'
};

fetch("https://api.catenda.com/opencde/foundation/versions", requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));
```

--------------------------------

### List API Versions using Python (Requests)

Source: https://developers.catenda.com/list-api-versions

This Python example uses the 'requests' library to list API versions. It sends a GET request with specified headers and prints the response text.

```python
import requests
import json

url = "https://api.catenda.com/opencde/foundation/versions"

payload = {}
headers = {
   'Accept': 'application/json',
   'Content-Type': 'application/json'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)
```

--------------------------------

### List API Versions using Ruby

Source: https://developers.catenda.com/list-api-versions

This Ruby snippet illustrates how to fetch API versions using the Net::HTTP library. It constructs a GET request and prints the response body.

```ruby
require "uri"
require "json"
require "net/http"

url = URI("https://api.catenda.com/opencde/foundation/versions")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Accept"] = "application/json"
request["Content-Type"] = "application/json"

response = https.request(request)
puts response.read_body
```

--------------------------------

### Get Auth URLs with Python

Source: https://developers.catenda.com/get-authentication-urls

Fetches authentication URLs from the Catenda API using Python's `requests` library. This example shows a common way to interact with REST APIs in Python.

```python
import requests
import json

url = "https://api.catenda.com/opencde/foundation/1.0/auth"

payload = {}
headers = {
   'Accept': 'application/json',
   'Content-Type': 'application/json'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)
```

--------------------------------

### GET /opencde/foundation/versions - List API Versions

Source: https://context7.com/context7/developers_catenda/llms.txt

Lists available OpenCDE API versions and their base URLs. This endpoint helps applications discover available API capabilities and construct proper API URLs.

```APIDOC
## GET /opencde/foundation/versions

### Description
List available OpenCDE API versions and their base URLs.

### Method
GET

### Endpoint
/opencde/foundation/versions

### Parameters

### Request Body

### Request Example
```bash
curl --location 'https://api.catenda.com/opencde/foundation/versions' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'
```

### Response
#### Success Response (200)
- **versions** (array) - A list of available API versions.
  - **api_id** (string) - The identifier for the API.
  - **version_id** (string) - The version identifier.
  - **detailed_version** (string) - A detailed description of the version.
  - **api_base_url** (string) - The base URL for this API version.

#### Response Example
```json
{
  "versions": [
    {
      "api_id": "bcf",
      "version_id": "3.0",
      "detailed_version": "Catenda OpenCDE BCF 3.0",
      "api_base_url": "https://api.catenda.com/opencde/bcf/3.0"
    }
  ]
}
```
```

--------------------------------

### GET /opencde/foundation/versions

Source: https://developers.catenda.com/list-api-versions

Fetches a list of all available API versions.

```APIDOC
## GET /opencde/foundation/versions

### Description
Retrieves a list of all available API versions for the Catenda OpenCDE foundation.

### Method
GET

### Endpoint
/opencde/foundation/versions

### Parameters
None

### Request Example
```json
{
  "example": ""
}
```

### Response
#### Success Response (200)
- **versions** (array) - A list of API version objects.
  - **api_id** (string) - The unique identifier for the API.
  - **version_id** (string) - The version identifier.
  - **detailed_version** (string) - A human-readable detailed version string.
  - **api_base_url** (string) - The base URL for this specific API version.

#### Response Example
```json
{
  "versions": [
    {
      "api_id": "bcf",
      "version_id": "3.0",
      "detailed_version": "Catenda OpenCDE BCF 3.0",
      "api_base_url": "https://api.catenda.com/opencde/bcf/3.0"
    }
  ]
}
```
```

--------------------------------

### GET /opencde/foundation/1.0/auth

Source: https://developers.catenda.com/get-authentication-urls

Retrieves the authentication URLs and supported OAuth2 flows.

```APIDOC
## GET /opencde/foundation/1.0/auth

### Description
Retrieves the authentication URLs and supported OAuth2 flows for the Catenda platform.

### Method
GET

### Endpoint
/opencde/foundation/1.0/auth

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "example": "No request body needed for this GET request."
}
```

### Response
#### Success Response (200)
- **oauth2_auth_url** (string) - The URL for OAuth2 authorization.
- **oauth2_token_url** (string) - The URL for obtaining OAuth2 tokens.
- **http_basic_supported** (boolean) - Indicates if HTTP Basic authentication is supported.
- **supported_oauth2_flows** (array) - A list of supported OAuth2 grant flows.

#### Response Example
```json
{
  "oauth2_auth_url": "https://api.catenda.com/oauth2/authorize",
  "oauth2_token_url": "https://api.catenda.com/oauth2/token",
  "http_basic_supported": false,
  "supported_oauth2_flows": [
    "authorization_code_grant"
  ]
}
```
```

--------------------------------

### List API Versions using cURL

Source: https://developers.catenda.com/list-api-versions

This snippet shows how to list available API versions using a simple cURL command. It sends a GET request to the specified endpoint with appropriate headers.

```curl
curl --location 'https://api.catenda.com/opencde/foundation/versions' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json'
```

--------------------------------

### Get Auth URLs with JavaScript

Source: https://developers.catenda.com/get-authentication-urls

Retrieves authentication URLs from the Catenda API using JavaScript's `fetch` API. This example shows how to handle asynchronous requests and process JSON responses.

```javascript
var myHeaders = new Headers();
myHeaders.append("Accept", "application/json");
myHeaders.append("Content-Type", "application/json");

var requestOptions = {
   method: 'GET',
   headers: myHeaders,
   redirect: 'follow'
};

fetch("https://api.catenda.com/opencde/foundation/1.0/auth", requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));
```

--------------------------------

### Link Header Example - HTML

Source: https://developers.catenda.com/pagination

This HTML snippet demonstrates the structure of the 'Link' header in Catenda API responses. It provides URLs for navigating through paginated resources, including links to the next, previous, first, and last pages. The 'pageSize' and 'page' parameters are used to specify the pagination details.

```html
<https://api.catenda.com/v2/projects/<RESOURCE>?pageSize=10&page=3>; rel="next",
<https://api.catenda.com/v2/projects/<RESOURCE>?pageSize=10&page=1>; rel="prev",
<https://api.catenda.com/v2/projects/<RESOURCE>?pageSize=10&page=1>; rel="first",
<https://api.catenda.com/v2/projects/<RESOURCE>?pageSize=10&page=5>; rel="last"
```

--------------------------------

### GET /opencde/foundation/1.0/auth - Get Authentication URLs

Source: https://context7.com/context7/developers_catenda/llms.txt

Retrieves OAuth 2.0 endpoint URLs and supported authentication flows. This endpoint follows the OpenCDE standard and requires no authentication.

```APIDOC
## GET /opencde/foundation/1.0/auth

### Description
Retrieve OAuth 2.0 endpoint URLs and supported authentication flows.

### Method
GET

### Endpoint
/opencde/foundation/1.0/auth

### Parameters

### Request Body

### Request Example
```bash
curl --location 'https://api.catenda.com/opencde/foundation/1.0/auth' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'
```

### Response
#### Success Response (200)
- **oauth2_auth_url** (string) - The URL for OAuth2 authorization.
- **oauth2_token_url** (string) - The URL for OAuth2 token exchange.
- **http_basic_supported** (boolean) - Indicates if HTTP Basic authentication is supported.
- **supported_oauth2_flows** (array) - A list of supported OAuth2 grant flows.

#### Response Example
```json
{
  "oauth2_auth_url": "https://api.catenda.com/oauth2/authorize",
  "oauth2_token_url": "https://api.catenda.com/oauth2/token",
  "http_basic_supported": false,
  "supported_oauth2_flows": ["authorization_code_grant"]
}
```
```

--------------------------------

### Get Auth URLs with Ruby

Source: https://developers.catenda.com/get-authentication-urls

Obtains authentication URLs from the Catenda API using Ruby's `net/http` library. This snippet demonstrates making HTTP GET requests and handling responses in Ruby.

```ruby
require "uri"
require "json"
require "net/http"

url = URI("https://api.catenda.com/opencde/foundation/1.0/auth")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Accept"] = "application/json"
request["Content-Type"] = "application/json"

response = https.request(request)
puts response.read_body
```

--------------------------------

### JavaScript API Error Handling Example

Source: https://context7.com/context7/developers_catenda/llms.txt

This snippet demonstrates how to make an API request and handle various HTTP errors. It checks for non-ok responses, parses JSON error data, and implements specific logic for different status codes like 400, 401 (including token refresh), 403, 404, 409, 422, and 500. Dependencies include the `fetch` API and potentially a `refreshAccessToken` function. It returns parsed JSON data on success or throws an error on failure.

```javascript
async function makeApiRequest(url, options) {
  try {
    const response = await fetch(url, options);

    if (!response.ok) {
      const errorData = await response.json();

      switch (response.status) {
        case 400:
          // Codes: 23 (empty file), 24 (incorrect field), 102 (invalid token)
          console.error('Bad Request:', errorData.message);
          break;
        case 401:
          // Codes: 10 (missing token), 11 (invalid token), 12 (expired token)
          if (errorData.code === 12) {
            // Token expired, attempt refresh
            await refreshAccessToken();
            return makeApiRequest(url, options); // Retry with new token
          }
          throw new Error('Unauthorized: ' + errorData.message);
        case 403:
          // Codes: 21 (forbidden), 100 (insufficient privilege), 101 (max projects)
          throw new Error('Forbidden: ' + errorData.message);
        case 404:
          // Code: 20 (resource not found)
          throw new Error('Not Found: ' + errorData.message);
        case 409:
          // Codes: 25 (incompatible action), 600 (custom field conflict)
          throw new Error('Conflict: ' + errorData.message);
        case 422:
          // Code: 22 (incompatible input)
          throw new Error('Unprocessable: ' + errorData.message);
        case 500:
          // Codes: 30 (server error), 103 (MFA required)
          throw new Error('Server Error: ' + errorData.message);
        default:
          throw new Error(`HTTP ${response.status}: ${errorData.message}`);
      }
    }

    return await response.json();
  } catch (error) {
    console.error('API request failed:', error);
    throw error;
  }
}

// Example error response structure:
// {
//   "code": 11,
//   "message": "The access token provided is empty or invalid"
// }
```

--------------------------------

### Get Auth URLs with cURL

Source: https://developers.catenda.com/get-authentication-urls

Fetches authentication URLs from the Catenda API using a cURL command. This is a simple, command-line approach for making the GET request.

```curl
curl --location 'https://api.catenda.com/opencde/foundation/1.0/auth' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json'
```

--------------------------------

### Get Current User API Request (cURL, JavaScript, Ruby, Python)

Source: https://developers.catenda.com/get-current-user

Demonstrates how to make a GET request to the '/current-user' endpoint of the Catenda API to retrieve the authenticated user's information. It includes examples for cURL, JavaScript (using fetch), Ruby, and Python (using requests). The request sets 'Accept' and 'Content-Type' headers to 'application/json'. The response is expected to be a JSON object containing the user's 'id' and 'name'.

```curl
curl --location 'https://api.catenda.com/opencde/foundation/1.0/current-user' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json'
```

```javascript
var myHeaders = new Headers();
myHeaders.append("Accept", "application/json");
myHeaders.append("Content-Type", "application/json");

var requestOptions = {
   method: 'GET',
   headers: myHeaders,
   redirect: 'follow'
};

fetch("https://api.catenda.com/opencde/foundation/1.0/current-user", requestOptions)
   .then(response => response.text())
   .then(result => console.log(result))
   .catch(error => console.log('error', error));
```

```ruby
require "uri"
require "json"
require "net/http"

url = URI("https://api.catenda.com/opencde/foundation/1.0/current-user")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Accept"] = "application/json"
request["Content-Type"] = "application/json"

response = https.request(request)
puts response.read_body
```

```python
import requests
import json

url = "https://api.catenda.com/opencde/foundation/1.0/current-user"

payload = {}
headers = {
   'Accept': 'application/json',
   'Content-Type': 'application/json'
}

response = requests.request("GET", url, headers=headers, data=payload)

print(response.text)
```

--------------------------------

### GET /opencde/foundation/1.0/current-user - Get Current User

Source: https://context7.com/context7/developers_catenda/llms.txt

Retrieves information about the currently authenticated user. Requires a valid OAuth 2.0 access token in the Authorization header.

```APIDOC
## GET /opencde/foundation/1.0/current-user

### Description
Retrieve information about the currently authenticated user.

### Method
GET

### Endpoint
/opencde/foundation/1.0/current-user

### Parameters
#### Query Parameters

#### Path Parameters

#### Request Body

### Request Example
```bash
curl --location 'https://api.catenda.com/opencde/foundation/1.0/current-user' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...'
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the user.
- **name** (string) - The display name of the user.

#### Response Example
```json
{
  "id": "john@doe.com",
  "name": "John Doe"
}
```
```

--------------------------------

### OpenCDE Foundation API: Get Authentication URLs (Bash)

Source: https://context7.com/context7/developers_catenda/llms.txt

Retrieves OAuth 2.0 endpoint URLs and supported authentication flows from the OpenCDE Foundation API. This endpoint is unauthenticated and follows the OpenCDE standard.

```bash
curl --location 'https://api.catenda.com/opencde/foundation/1.0/auth' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'
```

--------------------------------

### GET /opencde/foundation/1.0/current-user

Source: https://developers.catenda.com/get-current-user

Retrieves the details of the currently authenticated user.

```APIDOC
## GET /opencde/foundation/1.0/current-user

### Description
Retrieves the details of the currently authenticated user.

### Method
GET

### Endpoint
/opencde/foundation/1.0/current-user

### Parameters
#### Query Parameters
None

#### Request Body
None

### Request Example
```json
{
  "example": "No request body needed for this GET request."
}
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the user (e.g., email address).
- **name** (string) - The full name of the user.

#### Response Example
```json
{
  "id": "john@doe.com",
  "name": "John Doe"
}
```
```

--------------------------------

### OpenCDE Foundation API: Get Current User (Bash)

Source: https://context7.com/context7/developers_catenda/llms.txt

Retrieves information about the currently authenticated user via the OpenCDE Foundation API. Requires a valid OAuth 2.0 access token in the Authorization header.

```bash
curl --location 'https://api.catenda.com/opencde/foundation/1.0/current-user' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...'
```

--------------------------------

### OpenCDE Foundation API: List API Versions (Bash)

Source: https://context7.com/context7/developers_catenda/llms.txt

Lists available OpenCDE API versions and their base URLs from the OpenCDE Foundation API. This endpoint assists applications in discovering API capabilities and constructing correct API URLs.

```bash
curl --location 'https://api.catenda.com/opencde/foundation/versions' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json'
```

--------------------------------

### Pagination: Navigating Paginated Results (Bash)

Source: https://context7.com/context7/developers_catenda/llms.txt

Demonstrates how to request a specific page and item count for paginated API responses using page and pageSize parameters. The API provides Link and X-Total-Count headers for navigation.

```bash
# Request page 2 with 10 items per page
curl --location 'https://api.catenda.com/v2/projects/PROJECT_ID/models?page=2&pageSize=10' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...'
```

--------------------------------

### Pagination Parameters

Source: https://developers.catenda.com/pagination

This endpoint demonstrates how to use query parameters for pagination. You can specify the desired page number and the number of items per page.

```APIDOC
## GET /v2/projects/<RESOURCE>

### Description
This endpoint retrieves a paginated list of resources within a project. You can control the results by specifying the page number and the size of each page.

### Method
GET

### Endpoint
`/v2/projects/<RESOURCE>`

### Parameters
#### Query Parameters
- **page** (integer) - Optional - The page number to return. Defaults to 1.
- **pageSize** (integer) - Optional - The number of items to return in a response. Defaults to 100.

### Response
#### Success Response (200)
- **Link** (string) - Header containing URLs for navigating through pages (next, prev, first, last).
- **X-Total-Count** (integer) - Header indicating the total number of items available for the resource.

#### Response Example (Headers)
```
Link: <https://api.catenda.com/v2/projects/<RESOURCE>?pageSize=10&page=3>; rel="next", <https://api.catenda.com/v2/projects/<RESOURCE>?pageSize=10&page=1>; rel="prev", <https://api.catenda.com/v2/projects/<RESOURCE>?pageSize=10&page=1>; rel="first", <https://api.catenda.com/v2/projects/<RESOURCE>?pageSize=10&page=5>; rel="last"
X-Total-Count: 50
```
```

--------------------------------

### Pagination - Navigating Paginated Results

Source: https://context7.com/context7/developers_catenda/llms.txt

Handle paginated API responses using page and pageSize parameters. The API returns Link and X-Total-Count headers for navigation and tracking progress through large result sets.

```APIDOC
## GET /v2/projects/{PROJECT_ID}/models - Paginated Results

### Description
Retrieve paginated results for models within a project.

### Method
GET

### Endpoint
/v2/projects/{PROJECT_ID}/models

### Parameters
#### Path Parameters
- **PROJECT_ID** (string) - Required - The ID of the project.

#### Query Parameters
- **page** (integer) - Optional - The page number to retrieve.
- **pageSize** (integer) - Optional - The number of items per page.

### Request Example
```bash
# Request page 2 with 10 items per page
curl --location 'https://api.catenda.com/v2/projects/PROJECT_ID/models?page=2&pageSize=10' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...'
```

### Response
#### Success Response (200)
- Returns a JSON array of model objects.
- **Link** (header) - Provides URIs for navigating through pages (next, prev, first, last).
- **X-Total-Count** (header) - The total number of items available across all pages.

#### Response Example
```json
# Response includes headers:
# Link: <https://api.catenda.com/v2/projects/PROJECT_ID/models?pageSize=10&page=3>; rel="next",
#       <https://api.catenda.com/v2/projects/PROJECT_ID/models?pageSize=10&page=1>; rel="prev",
#       <https://api.catenda.com/v2/projects/PROJECT_ID/models?pageSize=10&page=1>; rel="first",
#       <https://api.catenda.com/v2/projects/PROJECT_ID/models?pageSize=10&page=5>; rel="last"
# X-Total-Count: 47

# Example JSON body (content will vary):
[
  { "id": "model1", "name": "Model A" },
  { "id": "model2", "name": "Model B" }
]
```

### JavaScript Pagination Example
```javascript
async function fetchAllPages(baseUrl, accessToken) {
  const results = [];
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const response = await fetch(`${baseUrl}?page=${page}&pageSize=100`, {
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Accept': 'application/json'
      }
    });

    const data = await response.json();
    results.push(...data);

    const linkHeader = response.headers.get('Link');
    hasMore = linkHeader && linkHeader.includes('rel="next"');
    page++;
  }

  return results;
}
```
```

--------------------------------

### Pagination: Navigating Paginated Results (JavaScript)

Source: https://context7.com/context7/developers_catenda/llms.txt

Provides a JavaScript function to fetch all paginated results from an API. It iteratively requests pages until no 'next' link is found in the response headers, accumulating all data.

```javascript
async function fetchAllPages(baseUrl, accessToken) {
  const results = [];
  let page = 1;
  let hasMore = true;

  while (hasMore) {
    const response = await fetch(`${baseUrl}?page=${page}&pageSize=100`, {
      headers: {
        'Authorization': `Bearer ${accessToken}`,
        'Accept': 'application/json'
      }
    });

    const data = await response.json();
    results.push(...data);

    const linkHeader = response.headers.get('Link');
    hasMore = linkHeader && linkHeader.includes('rel="next"');
    page++;
  }

  return results;
}
```

--------------------------------

### Authorization Code Grant with PKCE URL - Catenda API

Source: https://developers.catenda.com/authentication

This snippet demonstrates the URL for the Authorization Code Grant flow with the Proof Key for Code Exchange (PKCE) extension. It includes the client ID, redirect URI, and parameters for PKCE: code challenge method and code challenge.

```html
http://api.catenda.com/oauth2/authorize?client_id=<CLIENT_ID>&response_type=code&redirect_uri=<REDIRECT_URI>&code_challenge_method=S256&code_challenge=<CODE_CHALLENGE>
```

--------------------------------

### OAuth 2.0 Client Credentials Grant

Source: https://context7.com/context7/developers_catenda/llms.txt

Obtains an access token for server-to-server communication without user context. This flow is intended for applications accessing resources on their own behalf and is typically available for specific product tiers (e.g., Catenda Boost).

```bash
curl --request POST \
  --url https://api.catenda.com/oauth2/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data client_id=your_client_id \
  --data client_secret=your_client_secret \
  --data grant_type=client_credentials

# Response (no refresh token provided):
# {
#   "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
#   "token_type": "bearer",
#   "expires_in": 3600
# }
```

--------------------------------

### Authorization Code Grant with PKCE - Obtain Authorization Code

Source: https://developers.catenda.com/authentication

Enhance security by using the PKCE extension with the Authorization Code Grant flow. This requires generating a code challenge and verifier.

```APIDOC
## GET /oauth2/authorize (with PKCE)

### Description
Initiates the Authorization Code Grant flow with PKCE enabled by requesting an authorization code from the user.

### Method
GET

### Endpoint
`https://api.catenda.com/oauth2/authorize`

### Parameters
#### Query Parameters
- **client_id** (String) - Required - The `client_id` of the application making the request
- **response_type** (String) - Required - Value must be `code`
- **response_mode** (String) - Optional - Valid values are `query` or `fragment`, default is `query`
- **state** (String) - Optional - Additional state included in the response which may be useful for your application
- **redirect_uri** (String) - Required - The registered redirect URI of the application where the response will be sent
- **prompt** (String) - Optional - Whether Catenda will always prompt users to login or be remembered on future visits. Valid values are `login` and `none`
- **code_challenge_method** (String) - Required - The method used to generate the code challenge. Valid values are `S256`
- **code_challenge** (String) - Required - The code challenge is created by SHA256 hashing the code verifier

### Request Example
```html
http://api.catenda.com/oauth2/authorize?client_id=<CLIENT_ID>&response_type=code&redirect_uri=<REDIRECT_URI>&code_challenge_method=S256&code_challenge=<CODE_CHALLENGE>
```

### Response
#### Success Response (302 Found - Redirect)
- **code** (String) - The authorization code
- **state** (String) - State included in initial request

#### Response Example
(Redirect to `redirect_uri` with query parameters)
```

--------------------------------

### 404 Not Found Errors

Source: https://developers.catenda.com/errors

This section details specific error codes returned for 404 Not Found responses.

```APIDOC
## 404 Not Found

| Code | Description                          |
| ---- | ------------------------------------ |
| 20   | Couldn't find the specified resource |
```

--------------------------------

### OAuth 2.0 Authorization Code Grant - Obtain Authorization Code

Source: https://context7.com/context7/developers_catenda/llms.txt

Initiates the OAuth 2.0 Authorization Code Grant flow by redirecting users to the authorization endpoint. This is the first step for user-authenticated applications to gain access to resources. Supports both standard and PKCE-enhanced flows.

```html
<!-- Standard Authorization Code Grant -->
https://api.catenda.com/oauth2/authorize?client_id=your_client_id&response_type=code&redirect_uri=https://yourapp.com/callback

<!-- With PKCE for enhanced security -->
https://api.catenda.com/oauth2/authorize?client_id=your_client_id&response_type=code&redirect_uri=https://yourapp.com/callback&code_challenge_method=S256&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM

<!-- User redirected back with authorization code -->
<!-- https://yourapp.com/callback?code=AUTH_CODE_HERE&state=optional_state -->
```

--------------------------------

### OAuth 2.0 Authorization Code Grant - Obtaining Authorization Code

Source: https://context7.com/context7/developers_catenda/llms.txt

Initiates the OAuth 2.0 Authorization Code Grant flow by redirecting users to the authorization endpoint. Supports standard and PKCE flows for enhanced security.

```APIDOC
## OAuth 2.0 Authorization Code Grant - Obtaining Authorization Code

### Description
Redirect users to the authorization endpoint to obtain an authorization code for accessing resources on their behalf. This is the first step in the standard OAuth 2.0 flow for user-authenticated applications.

### Method
GET

### Endpoint
`/oauth2/authorize`

### Parameters
#### Query Parameters
- **client_id** (string) - Required - Your application's client ID.
- **response_type** (string) - Required - Must be set to `code`.
- **redirect_uri** (string) - Required - The URI to redirect the user back to after authorization.
- **code_challenge_method** (string) - Optional - The method used to derive the code challenge (e.g., `S256`). Used for PKCE.
- **code_challenge** (string) - Optional - The challenge generated for PKCE.
- **state** (string) - Optional - An opaque value used to maintain state between the request and callback.

### Request Example
```html
https://api.catenda.com/oauth2/authorize?client_id=your_client_id&response_type=code&redirect_uri=https://yourapp.com/callback

# With PKCE for enhanced security
https://api.catenda.com/oauth2/authorize?client_id=your_client_id&response_type=code&redirect_uri=https://yourapp.com/callback&code_challenge_method=S256&code_challenge=E9Melhoa2OwvFrEMTJguCHaoeK1t8URWbuGJSstw-cM
```

### Response
#### Success Response (Redirect)
Users are redirected to the specified `redirect_uri` with an authorization code in the query parameters.

#### Response Example
```html
https://yourapp.com/callback?code=AUTH_CODE_HERE&state=optional_state
```
```

--------------------------------

### POST /oauth2/token - Obtain Access Token

Source: https://developers.catenda.com/authentication

Exchanges an authorization code for an access token. Supports both standard and PKCE flows.

```APIDOC
## POST /oauth2/token - Obtain Access Token

### Description
Exchanges an authorization code for an access token. This endpoint is used after a user has authorized your application and granted it access.

### Method
POST

### Endpoint
https://api.catenda.com/oauth2/token

### Parameters
#### Query Parameters
- **client_id** (String) - Required - The client ID of the application.
- **client_secret** (String) - Required (unless using PKCE) - The client secret of the application.
- **code** (String) - Required - The authorization code obtained from the user.
- **grant_type** (String) - Required - Must be set to `authorization_code`.
- **redirect_uri** (String) - Required - The registered redirect URI.
- **code_verifier** (String) - Required (for PKCE) - A cryptographically random string used for PKCE.

### Request Example (Standard Flow)
```curl
curl --request POST \
  --url https://api.catenda.com/oauth2/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data client_id=<CLIENT_ID> \
  --data client_secret=<CLIENT_SECRET> \
  --data code=<AUTHORIZATION_CODE> \
  --data grant_type=authorization_code \
  --data redirect_uri=<REDIRECT_URI>
```

### Request Example (PKCE Flow)
```curl
curl --request POST \
  --url https://api.catenda.com/oauth2/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data client_id=<CLIENT_ID> \
  --data code=<AUTHORIZATION_CODE> \
  --data code_verifier=<CODE_VERIFIER> \
  --data grant_type=authorization_code \
  --data redirect_uri=<REDIRECT_URI>
```

### Response
#### Success Response (200)
- **access_token** (String) - The obtained access token.
- **refresh_token** (String) - The refresh token to obtain new access tokens.
- **token_type** (String) - The type of the token, typically `bearer`.
- **expires_in** (Integer) - The lifetime of the access token in seconds.

#### Response Example
```json
{
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "aBcDeFgHiJkLmNoPqRsTuVwXyZ1234567890abcdefghij",
  "token_type": "bearer",
  "expires_in": 3600
}
```
```

--------------------------------

### OAuth 2.0 Client Credentials Grant

Source: https://context7.com/context7/developers_catenda/llms.txt

Obtains an access token for server-to-server interactions. This grant type is suitable for applications accessing resources on their own behalf and is available for Catenda Boost customers.

```APIDOC
## OAuth 2.0 Client Credentials Grant

### Description
Obtain an access token for server-to-server communication without user context. This flow is available only for Catenda Boost customers and is used when applications access resources on their own behalf.

### Method
POST

### Endpoint
`/oauth2/token`

### Parameters
#### Request Body
- **grant_type** (string) - Required - Must be set to `client_credentials`.
- **client_id** (string) - Required - Your application's client ID.
- **client_secret** (string) - Required - Your application's client secret.

### Request Example
```bash
curl --request POST \
  --url https://api.catenda.com/oauth2/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data client_id=your_client_id \
  --data client_secret=your_client_secret \
  --data grant_type=client_credentials
```

### Response
#### Success Response (200)
- **access_token** (string) - The access token for authenticating API requests.
- **token_type** (string) - The type of token, usually `bearer`.
- **expires_in** (integer) - The lifetime in seconds of the access token.

#### Response Example
```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "token_type": "bearer",
  "expires_in": 3600
}
```
```

--------------------------------

### 422 Unprocessable Content Errors

Source: https://developers.catenda.com/errors

This section details specific error codes returned for 422 Unprocessable Content responses.

```APIDOC
## 422 Unprocessable Content

| Code | Description                    |
| ---- | ------------------------------ |
| 22   | Input provided is incompatible |
```

--------------------------------

### Obtaining an access token

Source: https://developers.catenda.com/authentication

This endpoint allows you to obtain an access token for authenticating with the Catenda API. You need to provide your client ID, client secret, and specify the grant type as 'client_credentials'.

```APIDOC
## POST /oauth2/token

### Description
Requests an access token using the token endpoint. This token is required for authenticating subsequent API requests.

### Method
POST

### Endpoint
https://api.catenda.com/oauth2/token

### Parameters
#### Request Body
- **client_id** (String) - Required - The client ID of the application.
- **client_secret** (String) - Required - The client secret of the application.
- **grant_type** (String) - Required - Must be set to `client_credentials`.

### Request Example
```json
{
  "client_id": "<CLIENT_ID>",
  "client_secret": "<CLIENT_SECRET>",
  "grant_type": "client_credentials"
}
```

### Response
#### Success Response (200)
- **access_token** (String) - The obtained access token.
- **token_type** (String) - The type of the token (e.g., Bearer).
- **expires_in** (Integer) - The time in seconds until the token expires.

#### Response Example
```json
{
  "access_token": "YOUR_ACCESS_TOKEN",
  "token_type": "Bearer",
  "expires_in": 3600
}
```
```

--------------------------------

### OAuth 2.0 Authorization Code Grant - Exchange Code for Access Token

Source: https://context7.com/context7/developers_catenda/llms.txt

Exchanges an authorization code obtained from the previous step for an access token and a refresh token. Supports flows with and without PKCE.

```APIDOC
## OAuth 2.0 Authorization Code Grant - Exchange Code for Access Token

### Description
Exchange the authorization code for an access token that can be used to authenticate API requests. The access token expires after one hour and includes a refresh token for obtaining new tokens.

### Method
POST

### Endpoint
`/oauth2/token`

### Parameters
#### Request Body
- **grant_type** (string) - Required - Must be set to `authorization_code`.
- **client_id** (string) - Required - Your application's client ID.
- **client_secret** (string) - Required (unless using PKCE) - Your application's client secret.
- **code** (string) - Required - The authorization code received from the `/oauth2/authorize` endpoint.
- **redirect_uri** (string) - Required - The same redirect URI used during the authorization request.
- **code_verifier** (string) - Optional - The verifier string used in the PKCE flow. Required if `code_challenge_method` was `S256` during authorization.

### Request Example
```bash
# Standard flow with client secret
curl --request POST \
  --url https://api.catenda.com/oauth2/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data client_id=your_client_id \
  --data client_secret=your_client_secret \
  --data code=authorization_code_from_previous_step \
  --data grant_type=authorization_code \
  --data redirect_uri=https://yourapp.com/callback

# PKCE flow without client secret
curl --request POST \
  --url https://api.catenda.com/oauth2/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data client_id=your_client_id \
  --data code=authorization_code_from_previous_step \
  --data code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk \
  --data grant_type=authorization_code \
  --data redirect_uri=https://yourapp.com/callback
```

### Response
#### Success Response (200)
- **access_token** (string) - The access token for authenticating API requests.
- **refresh_token** (string) - A token to obtain new access tokens.
- **token_type** (string) - The type of token, usually `bearer`.
- **expires_in** (integer) - The lifetime in seconds of the access token.

#### Response Example
```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "refresh_token_here",
  "token_type": "bearer",
  "expires_in": 3600
}
```
```

--------------------------------

### 400 Bad Request Errors

Source: https://developers.catenda.com/errors

This section details specific error codes returned for 400 Bad Request responses.

```APIDOC
## 400 Bad Request

| Code | Description                     |
| ---- | ------------------------------- |
| 23   | The uploaded file is empty      |
| 24   | Incorrect field or content in the request |
| 102  | Viewer token provided is invalid|
```

--------------------------------

### 500 Internal Server Error Errors

Source: https://developers.catenda.com/errors

This section details specific error codes returned for 500 Internal Server Error responses.

```APIDOC
## 500 Internal Server Error

| Code | Description                         |
| ---- | ----------------------------------- |
| 30   | Error occurred on the server        |
| 103  | Multi-factor authorization required |
```

--------------------------------

### Authorization Code Grant - Obtain Authorization Code

Source: https://developers.catenda.com/authentication

Initiate the Authorization Code Grant flow by redirecting the user to the authorize endpoint with the necessary query parameters.

```APIDOC
## GET /oauth2/authorize

### Description
Initiates the Authorization Code Grant flow by requesting an authorization code from the user.

### Method
GET

### Endpoint
`https://api.catenda.com/oauth2/authorize`

### Parameters
#### Query Parameters
- **client_id** (String) - Required - The `client_id` of the application making the request
- **response_type** (String) - Required - Value must be `code`
- **response_mode** (String) - Optional - Valid values are `query` or `fragment`, default is `query`
- **state** (String) - Optional - Additional state included in the response which may be useful for your application
- **redirect_uri** (String) - Required - The registered redirect URI of the application where the response will be sent
- **prompt** (String) - Optional - Whether Catenda will always prompt users to login or be remembered on future visits. Valid values are `login` and `none`

### Request Example
```html
http://api.catenda.com/oauth2/authorize?client_id=<CLIENT_ID>&response_type=code&redirect_uri=<REDIRECT_URI>
```

### Response
#### Success Response (302 Found - Redirect)
- **code** (String) - The authorization code
- **state** (String) - State included in initial request

#### Response Example
(Redirect to `redirect_uri` with query parameters)
```

--------------------------------

### OAuth 2.0 Authorization Code Grant - Exchange Code for Access Token

Source: https://context7.com/context7/developers_catenda/llms.txt

Exchanges an authorization code obtained from the previous step for an access token and a refresh token. The access token is used for authenticating API requests and expires in one hour. Supports standard flow with client secret and PKCE flow without client secret.

```bash
# Standard flow with client secret
curl --request POST \
  --url https://api.catenda.com/oauth2/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data client_id=your_client_id \
  --data client_secret=your_client_secret \
  --data code=authorization_code_from_previous_step \
  --data grant_type=authorization_code \
  --data redirect_uri=https://yourapp.com/callback

# Response:
# {
#   "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
#   "refresh_token": "refresh_token_here",
#   "token_type": "bearer",
#   "expires_in": 3600
# }

# PKCE flow without client secret
curl --request POST \
  --url https://api.catenda.com/oauth2/token \
  --header 'Content-Type: application/x-www-form-urlencoded' \
  --data client_id=your_client_id \
  --data code=authorization_code_from_previous_step \
  --data code_verifier=dBjftJeZ4CVP-mB92K27uhbUJU1p1r_wW1gFWFOEjXk \
  --data grant_type=authorization_code \
  --data redirect_uri=https://yourapp.com/callback
```

--------------------------------

### 409 Conflict Errors

Source: https://developers.catenda.com/errors

This section details specific error codes returned for 409 Conflict responses.

```APIDOC
## 409 Conflict

| Code | Description                                            |
| ---- | ------------------------------------------------------ |
| 25   | Action is incompatible with the specified resource     |
| 600  | Action is incompatible with the specified custom field |
```

--------------------------------

### 401 Unauthorized Errors

Source: https://developers.catenda.com/errors

This section details specific error codes returned for 401 Unauthorized responses.

```APIDOC
## 401 Unauthorized

| Code | Description                                   |
| ---- | --------------------------------------------- |
| 10   | The access token is missing                   |
| 11   | The access token provided is empty or invalid |
| 12   | The access token provided has expired         |
```