Using the Management API

Overview

The Champion Management API allows clients to perform file operations against the S3-backed knowledge base used by the Champion Server. Through this set of endpoints, users can list, upload, download, and delete objects in either an organization's or consumer's knowledge base bucket. This document outlines how to authenticate, construct requests, and handle responses when interacting with the Management API.

Prerequisites

1. Champion Token

All Management API calls require an OAuth2 "Champion" token obtained from Auth0. You must first acquire a valid access token (referred to as champion_token) before invoking any endpoint.

export client_id=ABC123...
export client_secret=REDACTED
export user_id=USER123...
http http://prep.ai.rz-ops.com/champion/api/oauth/token \
  "clientId=$client_id" \
  "clientSecret=$client_secret" \
  "userId=$user_id"

The JSON response will contain an access_token value. Set this as your champion_token environment variable.

2. HTTP Client

We recommend using HTTPie or curl to when testing the API requests. HTTPie examples are shown below for clarity.

3. Organization ID

When calling endpoints under /management/knowledge-base/{knowledgeBaseType}, you must supply an organizationId query parameter that identifies your organization context. This is a string such as org_kaafNUGj8r6dpokA.

Base URL

Environment Endpoints:

https://{environment}.rz-ops.com/champion/api

where {environment} can be one of:

lab.ai
prep.ai
ai (default)

Endpoint References

:::note All calls require the header:

Authorization: Bearer $champion_token

:::

1. List Objects in Knowledge Base

Endpoint:

GET /management/knowledge-base/{knowledgeBaseType}

Description: Returns a paginated list of object metadata from the S3 bucket.

Path Parameters:

knowledgeBaseType (string, required): Either organization or consumer.

Query Parameters:

organizationId (string, required): The ID of the organization to list objects for.
continuationToken (string, optional): Token to retrieve the next page of results.

Security Scopes:

read:organization-knowledge-base-content
read:consumer-knowledge-base-content

Response (200):

{
  "objects": [
    {
      "key": "test/example/test.txt",
      "size": 1234,
      "lastModified": "2025-05-01T12:34:56Z",
      "contentType": "text/plain"
    }
    // ... up to maxKeys entries
  ],
  "nextToken": "abcdef123456" // optional, for pagination
}

objects (array of ObjectMetadata): Each entry has:
- key (string)
- size (integer)
- lastModified (string, date-time)
- contentType (string)
nextToken (string, optional): Use to fetch the next page.

Example HTTPie Request (List up to 100 objects):

http GET http://prep.ai.rz-ops.com/champion/api/management/knowledge-base/organization?organizationId=org_ID \
  "Authorization: Bearer $champion_token"

Replace organization with consumer if listing consumer KB.
Adjust organizationId and maxKeys as needed.

2. Get Upload URL

Endpoint:

POST /management/knowledge-base/{knowledgeBaseType}/upload-url

Description: Generates a pre-signed URL and form fields for uploading a file to S3.

Path Parameters:

knowledgeBaseType (string, required): organization or consumer.

Query Parameters:

organizationId (string, required): Organization ID associated with the upload.

Request Body (application/json):

{
  "fileName": "test.txt",             // required
  "contentType": "text/plain",        // required (MIME type)
  "filePath": "test/example",         // optional (folder/subfolder)
  "metadata": {                       // optional
    "originUrl": "https://example.com/test.txt",
    "originName": "test.txt",
    "originSourceName": "local-upload",
    "version": "1.0",
    "product": "champion"
  }
}

fileName (string, required): The target filename in S3.
contentType (string, required): MIME type, e.g., text/plain.
filePath (string, optional): The S3 folder path (e.g., folder/subfolder/).
metadata (object, optional): User-defined metadata for the file.

Security Scopes:

write:organization-knowledge-base-content
write:consumer-knowledge-base-content

Response (200):

{
  "url": "https://s3.amazonaws.com/....",
  "fields": {
    "key": "test/example/test.txt",
    "policy": "base64-encoded-policy",
    "x-amz-algorithm": "AWS4-HMAC-SHA256",
    "x-amz-credential": "...",
    "x-amz-date": "20250605T000000Z",
    "x-amz-signature": "abcdef123456"
  },
  "expiresAt": "2025-06-06T00:00:00Z"
}

url (string): The S3 host and bucket to which the file should be uploaded.
fields (object): Form fields required for a browser-based (POST) upload.
expiresAt (string, date-time): When the pre-signed URL expires.

Example HTTPie Request (Generate Upload URL):

http --json POST http://prep.ai.rz-ops.com/champion/api/management/knowledge-base/organization/upload-url \
  organizationId=={ORGANIZATION_ID} \
  fileName="test.txt" \
  contentType="text/plain" \
  filePath="test/example" \
  metadata='{\"originUrl\":\"https://example.com/test.txt\",\"originName\":\"test.txt\",\"originSourceName\":\"local-upload\",\"version\":\"1.0\",\"product\":\"champion\"}' \
  "Authorization: Bearer $champion_token"

Copy the returned url and fields for the actual file upload.

Performing the Upload: Once you have uploadUrlResponse.url and uploadUrlResponse.fields, you can upload with:

http PUT "$uploadUrlResponse.url" @filename "Content-Type:text/plain"

Adjust @ syntax to point to your local file.

3. Get Download URL

Endpoint:

POST /management/knowledge-base/{knowledgeBaseType}/download-url

Description: Generates a pre-signed URL for downloading a file from S3.

Path Parameters:

knowledgeBaseType (string, required): organization or consumer.

Request Body (application/json):

{
  "fileName": "test.txt",       // required
  "filePath": "test/example"    // optional (folder path)
}

fileName (string, required): The exact name of the file to download.
filePath (string, optional): The folder path where the file resides.

Security Scopes:

read:organization-knowledge-base-content
read:consumer-knowledge-base-content

Response (200):

{
  "url": "https://s3.amazonaws.com/....?X-Amz-Signature=abcdef...",
  "expiresAt": "2025-06-06T00:00:00Z"
}

url (string): The pre-signed download link.
expiresAt (string, date-time): Expiration timestamp for the download URL.

Example HTTPie Request (Generate Download URL):

http --json POST http://prep.ai.rz-ops.com/champion/api/management/knowledge-base/organization/download-url \
  "Authorization: Bearer $champion_token" \
  fileName="test.txt" \
  filePath="test/example"

Use the returned url to perform a GET and save the file:

http --download $downloadUrlResponse.url

4. Delete Object

Endpoint:

DELETE /management/knowledge-base/{knowledgeBaseType}

Description: Deletes a file and its associated metadata from the S3 bucket.

Path Parameters:

knowledgeBaseType (string, required): organization or consumer.

Query Parameters:

organizationId (string, required): Organization ID under which the deletion occurs.

Request Body (application/json):

{
  "fileName": "test.txt",       // required
  "filePath": "test/example"    // optional (folder path)
}

fileName (string, required): The name of the file to delete.
filePath (string, optional): Folder path where the file resides.

Security Scopes:

delete:organization-knowledge-base-content
delete:consumer-knowledge-base-content

Response:

204 No Content: Deletion succeeded (no response body).
401 Unauthorized or 403 Forbidden: Invalid token or insufficient scopes.
404 Not Found: The specified file does not exist.

Example HTTPie Request (Delete File):

http --json DELETE http://prep.ai.rz-ops.com/champion/api/management/knowledge-base/organization \
  organizationId=={ORGANIZATION_ID} \
  fileName="test.txt" \
  filePath="test/example" \
  "Authorization: Bearer $champion_token"

On success, you will receive a 204 No Content with no JSON body.

Common Error Responses

401 Unauthorized

Occurs when the Authorization header is missing, invalid, or expired.
Ensure that champion_token is correctly retrieved and passed with each request.

403 Forbidden

The token is valid but does not have the required OAuth2 scope.
Check that the token was requested with the proper scopes (e.g., read:organization-knowledge-base-content).

404 Not Found

For download/delete endpoints, indicates that the specified file does not exist under the given filePath or knowledgeBaseType.
Confirm the correct fileName, filePath, and knowledgeBaseType.

Tips & Best Practices

Pagination

When listing large buckets, use the nextToken from the previous response to retrieve subsequent pages:

http GET "http://prep.ai.rz-ops.com/champion/api/management/knowledge-base/organization?organizationId=org_ID" \
  continuationToken=="abcdef123456" \
  "Authorization: Bearer $champion_token"

Continue until nextToken is null or absent.

Folder Paths

If you do not specify filePath, the object is assumed to be in the bucket's root.
Always URL-encode paths with special characters (spaces, plus signs, etc.) when constructing requests.

Metadata Usage

The metadata object in the upload request is stored as user-defined metadata on the S3 object.

Using the Management API

Directory

Overview

Prerequisites

1. Champion Token

2. HTTP Client

3. Organization ID

Base URL

Endpoint References

1. List Objects in Knowledge Base

2. Get Upload URL

3. Get Download URL

4. Delete Object

Common Error Responses

401 Unauthorized

403 Forbidden

404 Not Found

Tips & Best Practices

Pagination

Folder Paths

Metadata Usage