UsageGuard LogoDocs

Document APIs

The Document APIs enable you to manage document uploads, processing, and retrieval. For detailed information about document processing capabilities, see our Document Processing guide.

POST/v1/management/documents/upload/presign

Get Upload URL

Generate a pre-signed URL for uploading a document. This URL will be valid for 10 minutes and allows you to securely upload files to our storage.

Request Headers

  • Name
    x-connection-id
    Type
    string
    Description

    Your connection identifier. You can find this in your dashboard under Connections section.

  • Name
    x-api-key
    Type
    string
    Description

    Your API key for authentication. You can generate this from your dashboard under API Keys section.

Request Body

  • Name
    fileName
    Type
    string
    Description

    Name of the file you want to upload

  • Name
    contentType
    Type
    string
    Description

    The MIME type of the file (e.g., 'application/pdf', 'image/jpeg')

Request

POST
/v1/management/documents/upload/presign
curl -X POST https://api.usageguard.com/v1/management/documents/upload/presign \
  -H "x-connection-id: {connection_id}" \
  -H "x-api-key: {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "fileName": "document.pdf",
    "contentType": "application/pdf"
  }'

Response

{
  "url": "https://storage.usageguard.com/presigned-url",
  "key": "doc_abc123xyz"
}

400: Bad Request

{
  "error": "Bad Request",
  "message": "Invalid request. Ensure both fileName and contentType are provided and valid."
}
POST/v1/management/documents/upload/finalize

Finalize Upload

Finalize a document upload and create its metadata record. Call this after successfully uploading a file using the pre-signed URL.

Request Headers

  • Name
    x-connection-id
    Type
    string
    Description

    Your connection identifier. You can find this in your dashboard under Connections section.

  • Name
    x-api-key
    Type
    string
    Description

    Your API key for authentication. You can generate this from your dashboard under API Keys section.

Request Body

  • Name
    key
    Type
    string
    Description

    The key received from the pre-sign upload endpoint

  • Name
    fileName
    Type
    string
    Description

    Name of the uploaded file

  • Name
    fileSizeKb
    Type
    number
    Description

    Size of the file in kilobytes

  • Name
    fileExtension
    Type
    string
    Description

    File extension (e.g., 'pdf', 'docx')

  • Name
    classification
    Type
    string
    Description

    Document classification level. Defaults to 'confidential'

  • Name
    tags
    Type
    string
    Description

    Comma-separated tags for the document

Request

POST
/v1/management/documents/upload/finalize
curl -X POST https://api.usageguard.com/v1/management/documents/upload/finalize \
  -H "x-connection-id: {connection_id}" \
  -H "x-api-key: {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "doc_abc123xyz",
    "fileName": "document.pdf",
    "fileExtension": "pdf",
    "classification": "confidential",
    "tags": "contract,legal",
    "fileSizeKb": 1024
  }'

Response

{
  "status": "success",
  "message": "Document finalized successfully"
}

400: Bad Request

{
  "error": "Bad Request",
  "message": "Failed to finalize upload. Invalid file key or missing required fields."
}
GET/v1/management/documents

List Documents

Retrieve a paginated list of documents in your organization. Use this to browse and search through your document library.

Request Headers

  • Name
    x-connection-id
    Type
    string
    Description

    Your connection identifier. You can find this in your dashboard under Connections section.

  • Name
    x-api-key
    Type
    string
    Description

    Your API key for authentication. You can generate this from your dashboard under API Keys section.

Query Parameters

  • Name
    status
    Type
    string
    Description

    Filter documents by processing status

  • Name
    page
    Type
    integer
    Description

    Page number for pagination (minimum: 1). Defaults to 1

  • Name
    pageSize
    Type
    integer
    Description

    Number of items per page (range: 1-100). Defaults to 10

Request

GET
/v1/management/documents
curl https://api.usageguard.com/v1/management/documents?page=1&pageSize=10 \
  -H "x-connection-id: {connection_id}" \
  -H "x-api-key: {api_key}"

Response

{
  "items": [
    {
      "fileName": "document.pdf",
      "fileExtension": "pdf",
      "classification": "confidential",
      "tags": "contract,legal",
      "documentIdentifier": "doc_abc123xyz",
      "fileSizeKB": 1024,
      "processingStatus": "completed",
      "createdOnUtc": "2024-03-15T10:30:00Z",
      "updatedOnUtc": "2024-03-15T10:35:00Z"
    }
  ],
  "page": 1,
  "pageSize": 10,
  "totalCount": 45,
  "totalPages": 5
}

400: Bad Request

{
  "error": "Bad Request",
  "message": "Invalid request parameters. Ensure page and pageSize are within valid ranges."
}

Document Management


POST/v1/management/documents/status

Check Document Status

Check the processing status of one or more documents. Use this to monitor the progress of document processing.

Request Body

  • Name
    documentIdentifiers
    Type
    array
    Description

    Array of document identifiers to check status for

Request

POST
/v1/management/documents/status
curl -X POST https://api.usageguard.com/v1/management/documents/status \
  -H "x-connection-id: {connection_id}" \
  -H "x-api-key: {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "documentIdentifiers": ["doc_abc123xyz", "doc_def456uvw"]
  }'

Response

{
  "error": false,
  "data": [
    {
      "documentIdentifier": "doc_abc123xyz",
      "processingStatus": "completed",
      "lastProcessingError": null
    },
    {
      "documentIdentifier": "doc_def456uvw",
      "processingStatus": "processing",
      "lastProcessingError": null
    }
  ]
}

400: Bad Request

{
  "error": "Bad Request",
  "message": "Invalid request. Ensure you've provided at least one document identifier."
}
PUT/v1/management/documents

Update Document Metadata

Update document metadata such as classification and tags. Use this to modify document properties after upload.

Request Body

  • Name
    key
    Type
    string
    Description

    Document identifier

  • Name
    classification
    Type
    string
    Description

    New classification level for the document

  • Name
    tags
    Type
    string
    Description

    Updated comma-separated tags

Request

PUT
/v1/management/documents
curl -X PUT https://api.usageguard.com/v1/management/documents \
  -H "x-connection-id: {connection_id}" \
  -H "x-api-key: {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "key": "doc_abc123xyz",
    "classification": "restricted",
    "tags": "contract,legal,updated"
  }'

Response

{
  "status": "success",
  "message": "Document metadata updated successfully"
}

400: Bad Request

{
  "error": "Bad Request",
  "message": "Update failed. Invalid classification value or missing required fields."
}
DELETE/v1/management/documents

Delete Document

Delete one or more documents. Warning: This action cannot be undone. Make sure to backup any important documents before deletion.

Request Body

  • Name
    documentIdentifier
    Type
    string
    Description

    Identifier of the document to delete

Request

DELETE
/v1/management/documents
curl -X DELETE https://api.usageguard.com/v1/management/documents \
  -H "x-connection-id: {connection_id}" \
  -H "x-api-key: {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "documentIdentifier": "doc_abc123xyz"
  }'

Response

{
  "status": "success",
  "message": "Document deleted successfully"
}

400: Bad Request

{
  "error": "Bad Request",
  "message": "Delete request failed. Document not found or insufficient permissions."
}
POST/v1/management/documents/process

Process Document

Initiates or restarts document processing. This endpoint can be used to process documents that are in a failed state or to reprocess documents with updated settings.

Required headers

  • Name
    Authorization
    Type
    string
    Description

    Bearer token for authentication

Response

  • Name
    status
    Type
    number
    Description

    HTTP 200 on success

Request

POST
/v1/management/documents/process
curl -X POST https://api.example.com/v1/management/documents/process \
  -H "Authorization: Bearer {token}"

Response

200 OK
POST/v1/management/documents/download/presign

Get Download URL

Generate a pre-signed URL for downloading a document. This URL will be valid for 5 minutes and provides secure access to download your file.

Request Body

  • Name
    documentIdentifier
    Type
    string
    Description

    The unique identifier of the document you want to download

  • Name
    contentType
    Type
    string
    Description

    The MIME type of the file

Request

POST
/v1/management/documents/download/presign
curl -X POST https://api.usageguard.com/v1/management/documents/download/presign \
  -H "x-connection-id: {connection_id}" \
  -H "x-api-key: {api_key}" \
  -H "Content-Type: application/json" \
  -d '{
    "documentIdentifier": "doc_abc123xyz",
    "contentType": "application/pdf"
  }'

Response

{
  "url": "https://storage.usageguard.com/download-presigned-url",
  "key": "doc_abc123xyz"
}

400: Bad Request

{
  "error": "Bad Request",
  "message": "Invalid request. Verify that the documentIdentifier exists and you have permission to access it."
}

Document Search Function

UsageGuard provides a built-in function sys_search_documents that allows you to perform semantic searches across your document library. This function uses vector search to find documents that are semantically relevant to your search phrases.

Using the Function

You can use the sys_search_documents function in two ways:

  1. In Inference Requests: Include the function in your inference API requests by adding it to the tools array in your request body.

  2. In Prompt Templates: Define the function in your prompt templates to automatically search for relevant documents when the any request is made to a connection with the prompt is configured.

Function Schema

  • Name
    search_phrases
    Type
    array
    Description

    List of semantic search phrases to perform vector search for relevant documents

  • Name
    limit
    Type
    integer
    Description

    Maximum number of documents to retrieve. Defaults to 5

Example Usage

Here's an example of how to use the sys_search_documents function to find relevant airline policy documents:

{
  "search_phrases": [
    "airline baggage allowance policy",
    "checked luggage size restrictions",
    "carry-on baggage rules",
    "international flight baggage requirements"
  ],
  "limit": 5
}

The function will return documents that are semantically related to airline baggage policies, such as:

  • International baggage allowance guidelines
  • Carry-on size restrictions
  • Checked baggage weight limits
  • Special items transportation policies

Response Format

The function returns an array of matching documents with their relevance scores:

{
  "documents": [
    {
      "documentIdentifier": "doc_airline_policy_123",
      "fileName": "International_Baggage_Policy.pdf",
      "relevanceScore": 0.92,
      "snippet": "International flights allow up to 2 checked bags with a maximum weight of 23kg each..."
    },
    {
      "documentIdentifier": "doc_airline_policy_456",
      "fileName": "Carry_On_Restrictions.pdf",
      "relevanceScore": 0.88,
      "snippet": "Carry-on luggage must not exceed 56cm x 36cm x 23cm and must fit in the overhead bin..."
    }
  ]
}

Best Practices

  1. Use specific, descriptive search phrases that capture the essence of what you're looking for
  2. Include multiple related phrases to improve search accuracy
  3. Adjust the limit based on your needs - higher limits may return more results but take longer to process
  4. Consider the context of your search - the function works best with semantically related concepts

Error Handling

The function may return the following error responses:

400: Bad Request

{
  "error": "Bad Request",
  "message": "Invalid request. Search phrases must be provided and must be an array of strings."
}

404: Not Found

{
  "error": "Not Found",
  "message": "No documents found matching the search criteria."
}

Was this page helpful?