UpSearchManage API keys

On this page

  • Overview
  • Authentication
  • Search
  • Endpoint reference

Reference

  • Validation
  • Libraries
  • Documents
  • Search

Guides

  • Getting started
  • Response objects
On this page
  • Overview
  • Authentication
  • Search
  • Endpoint reference
Quickstart

1. Set your API key

export UPSEARCH_API_KEY="your-api-key"

2. Make a search request

curl https://api.upsearch.eu/api/v1/search/documents \
  -X POST \
  -H "x-api-key: $UPSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"security policy","documents":["document-id-1"],"limit":5,"enhancedSearch":true}'

Developer documentation

UpSearch API

Connect UpSearch to your products and internal systems. Use an organization API key from your backend to list libraries and documents, search content, and open verified source files.

Base URL

Send production API requests to:

https://api.upsearch.eu

Authentication

Create a named key in the developer dashboard. The complete key is shown only once, so copy it into your server's secret manager immediately. Every API request sends the key in thex-api-keyheader.

Search example

Send a natural-language query with either a document or library scope. Results are source passages—not generated answers.

curl "https://api.upsearch.eu/api/v1/search/documents" \
  -X POST \
  -H "x-api-key: $UPSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "What are our vendor security requirements?",
    "documents": ["document-id-1", "document-id-2"],
    "filters": [
      { "key": "tags", "value": ["security", "vendor"] },
      { "key": "valid", "value": "true" }
    ],
    "operator": "and",
    "limit": 5,
    "enhancedSearch": true
  }'

Request fields

query
Required string containing the natural-language search term.
documents or libraries
Required array defining the search scope. Provide one of these fields.
documentsToExclude
Optional document IDs to exclude when searching libraries.
filters
Optional custom-field criteria using key and value pairs.
operator
Required with filters. Use and to match all filters or or to match at least one.
limit
Required integer setting the maximum number of results.
enhancedSearch
Boolean that enables a final reranking step when true.

Result fields

idThe search-result record identifier.

documentIdThe source document identifier.

documentTitleThe source document title.

headingThe section heading around the match.

contextThe matching source passage.

pageThe page index returned by the backend.

imageUrlA rendered image for the matching page.

customFieldsThe custom metadata attached to the source document.

More search request examples

Choose the scope and optional filtering pattern that matches your integration.

Search documentsSearch across specific documents.
{
  "query": "search term",
  "documents": ["document_id_1", "document_id_2"],
  "limit": 5,
  "enhancedSearch": true
}
Search documents with filtersSearch specific documents and apply custom-field filters.
{
  "query": "search term",
  "documents": ["document_id_1", "document_id_2"],
  "filters": [
    { "key": "my_custom_field_1", "value": ["x", "y", "z"] },
    { "key": "my_custom_field_2", "value": "true" }
  ],
  "operator": "or",
  "limit": 5,
  "enhancedSearch": true
}
Search librariesSearch across specific libraries.
{
  "query": "search term",
  "libraries": ["library_id_1", "library_id_2"],
  "limit": 5,
  "enhancedSearch": true
}
Search libraries with filtersSearch specific libraries and apply custom-field filters.
{
  "query": "search term",
  "libraries": ["library_id_1", "library_id_2"],
  "filters": [
    { "key": "my_custom_field_1", "value": ["x", "y", "z"] },
    { "key": "my_custom_field_2", "value": "true" }
  ],
  "operator": "or",
  "limit": 5,
  "enhancedSearch": true
}
Search libraries with exclusionsSearch libraries with filters while excluding selected documents.
{
  "query": "search term",
  "libraries": ["library_id_1", "library_id_2"],
  "documentsToExclude": ["document_id_1", "document_id_2"],
  "filters": [
    { "key": "my_custom_field_1", "value": ["x", "y", "z"] },
    { "key": "my_custom_field_2", "value": "true" }
  ],
  "operator": "or",
  "limit": 5,
  "enhancedSearch": true
}

Response objects

These objects are referenced by the endpoint responses below.

LibraryObjectA complete library record.
{
  "id": "library_id_1",
  "libraryName": "Vestibulum ante",
  "description": "Donec bibendum diam ut pulvinar maximus.",
  "numberOfDocs": 84,
  "libraryMembers": ["user_1", "user_2"],
  "libraryAdmins": ["user_3"],
  "active": true,
  "createdAt": "2026-02-06T12:45:12.148Z",
  "updatedAt": "2026-02-17T12:19:17.35Z"
}
DocumentSummaryObjectUsed when listing documents within a library.
{
  "documentId": "document_id_1",
  "documentTitle": "Lorem ipsum",
  "createdAt": "2026-02-06T13:04:47.472Z",
  "updatedAt": "2026-02-06T13:04:47.472Z"
}
DocumentObjectUsed when retrieving full document details.
{
  "id": "document_id_1",
  "documentTitle": "Lorem ipsum",
  "documentDescription": "Aliquam venenatis nisl a vehicula varius.",
  "numberOfPages": 11,
  "numberOfUsers": 1,
  "coverPageUrl": "https://swift.elastx.cloud/...",
  "keywords": "keyword1,keyword2,keyword3",
  "libraries": [
    {
      "libraryId": "library_id_1",
      "libraryName": "Vestibulum ante",
      "updatedAt": "2026-02-06T13:04:48.04Z"
    }
  ],
  "status": {
    "status": "Completed",
    "progress": 100,
    "message": "Preparation complete."
  },
  "customFields": [
    {
      "key": "tags",
      "value": ["x", "y"],
      "unit": "My unit",
      "type": "List"
    }
  ],
  "createdAt": "2026-02-06T13:04:02.342Z",
  "updatedAt": "2026-02-06T13:04:02.342Z"
}
SearchResultObjectA source passage returned by search.
{
  "id": "record_id_1",
  "documentId": "document_id_1",
  "documentTitle": "Lorem ipsum",
  "heading": "Vivamus condimentum",
  "context": "Lorem ipsum dolor sit amet, consectetur adipiscing elit...",
  "page": 0,
  "imageUrl": "https://swift.elastx.cloud/...",
  "customFields": []
}
CustomFieldObjectA document metadata field.
{
  "key": "tags",
  "value": ["x"],
  "unit": "My unit",
  "type": "List"
}

Endpoint reference

All endpoints require thex-api-keyheader. Expand an endpoint to see its inputs, return value, and documented errors.

Validation

Confirm that a key is accepted before starting an integration.

GET

Validate API key

/api/v1/validate/key

Checks whether the supplied API key is valid.

Input

Header: x-api-key

Returns

Plain text confirmation: API Key is valid!

Other responses

  • 401 Unauthorized — Invalid API Key!
  • 404 Not Found — Missing header 'x-api-key'. Please provide an API Key.

Libraries

Discover the libraries and document collections available to the organization.

GET

Get library

/api/v1/library/get-library

Returns one library and its metadata.

Input

Query parameter: id (library ID)

Returns

LibraryObject

Other responses

  • 401 Unauthorized — Invalid API Key!
POST

Get libraries

/api/v1/library/get-libraries

Returns a selected set of libraries by ID.

Input

JSON body: { "ids": ["library-id-1", "library-id-2"] }

Returns

LibraryObject[]

GET

Get all libraries

/api/v1/library/get-all-libraries

Lists all libraries available to the API key's organization.

Input

No query parameters or request body.

Returns

LibraryObject[]

GET

Get library documents

/api/v1/library/get-library-documents

Lists the documents assigned to one library.

Input

Query parameter: id (library ID)

Returns

DocumentSummaryObject[] with documentId, documentTitle, createdAt, and updatedAt.

Documents

Retrieve document metadata, filter document sets, and open original source files.

GET

Get document

/api/v1/document/get-document

Returns metadata for one document.

Input

Query parameter: id (document ID)

Returns

DocumentObject

POST

Get documents

/api/v1/document/get-documents

Returns metadata for a selected set of documents.

Input

JSON body: { "documentIds": ["document-id-1", "document-id-2"] }

Returns

DocumentObject[]

GET

Get all documents

/api/v1/document/get-all-documents

Lists all documents available to the organization.

Input

No query parameters or request body.

Returns

DocumentObject[]

POST

Get documents from custom filter

/api/v1/document/get-documents-from-custom-filter

Finds documents whose custom fields match the supplied filters.

Input

JSON body: filters [{ key, value }] plus operator ("and" or "or"). Values may be strings or arrays.

Returns

DocumentObject[]

GET

View document

/api/v1/document/view-document

Creates a temporary link for opening the original PDF.

Input

Query parameter: id (document ID)

Returns

A time-limited signed PDF URL as plain text.

Search

Search selected documents and return source passages with page-level provenance.

POST

Search documents

/api/v1/search/documents

Searches document content using a natural-language query and a required document or library scope.

Input

JSON body: query; documents or libraries; optional documentsToExclude and filters; operator; limit; and enhancedSearch.

Returns

SearchResultObject[]

Quickstart (cURL)

1Set your API key

export UPSEARCH_API_KEY="your-api-key"

2Make a search request

curl https://api.upsearch.eu/api/v1/search/documents \
  -X POST \
  -H "x-api-key: $UPSEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "security policy",
    "documents": ["document-id-1"],
    "limit": 5,
    "enhancedSearch": true
  }'

Notes

  • Server-to-server only

    Never expose an API key in browser or mobile code.

  • Keep keys secure

    Store each key in a secret manager and remove it when it is no longer needed.

Create or manage a key