Files

This page documents the file-handling endpoints in the Event History API microservice.

The Files API supports event workflows where a history event must reference a file stored in S3. Before an event with an associated file can be recorded, the file must first be uploaded through the Event History service flow using a presigned URL.

At a high level, the process is:

1. The Event History API generates a presigned S3 upload URL
2. The client uploads the file directly to S3 using that URL
3. The file is then referenced by a related history event record

The presigned URL is generated by the Event History API microservice using AWS credentials with access to the target object storage. The URL is exposed to the calling service and remains valid only for a limited period of time.

WARNING

This section documents technical and service-level Event History APIs and is intended for internal platform use and controlled engineering workflows. It should not be treated as part of the main general-purpose external Catalyst integration surface. This area is outside general support coverage, so please contact your Customer Success team if you need guidance.

API overview

This page covers the following endpoint:

• GET /api/files/upload-url

---

GET /api/files/upload-url

Generates a presigned URL for uploading a file to S3.

The file key prefix is based on the client instance database name. See Tenants for the related tenant model. The client instance is identified through the X-Client-Id header, and a UUID v4 is generated for the file name.

Permissions

Requires authentication.

Request

Headers

Request Method: GET
Content-Type: application/json
X-API-Key: API_KEY
X-Client-Id: client_id

Response

Success

• Status: 200 OK

Key	Type	Notes
upload_url	string	Presigned URL for uploading the file to S3
file_id	string	Unique file identifier

Response example

{
  "upload_url": "https://s3.eu-west-2.amazonaws.com/cluster-1-namespace-2/alx_demo/1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p",
  "file_id": "1a2b3c4d-5e6f-7g8h-9i0j-1k2l3m4n5o6p"
}

Errors

Error	Response code	Message
Tenant not found	400 Bad Request	"detail": "'{tenant}' tenant not found in database."
Client ID header is missing	400 Bad Request	"detail": "Unauthorized Client."
Client from header does not match any tenant	400 Bad Request	"detail": "Failed to connect to tenant db."
Wrong API key	401 Unauthorized	"detail": "Unauthorized API Key."
Missing authorization header	401 Unauthorized	"detail": "Unauthorized API Key."
Any request method other than GET is used	405 Method Not Allowed