Agentuity Documentation

Semantic search with automatic embedding generation.

Region

https://catalyst-usw.agentuity.cloud

Authentication

All requests require a Bearer token. Pass your SDK key in the Authorization header.

Header	Value
`Authorization`	`Bearer YOUR_SDK_KEY`

You can find your SDK key in the Agentuity Console under your project settings.

Upsert Vectors

Create or update vectors in a namespace. Provide either document (auto-embeds) or pre-computed embeddings per item.

PUT/vector/{namespace}

https://catalyst-usw.agentuity.cloud/vector/{namespace}

Parameters

path

Name	Type	Required	Description
`namespace`	string	Yes	The namespace name

Request Body

JSON array of vector documents to upsert.

Field	Type	Description
`key`	string	the key of the vector object which can be used as a reference. the value of this key is opaque to the vector storage.
`metadata`	object	the metadata to upsert (optional)
`ttl`	number \| null	Time-to-live in seconds for the vector. Controls when the vector expires and is automatically deleted. (optional)

Response

JSON response with inserted/updated vector IDs.

Status	Description
200	Vectors upserted successfully
401	Unauthorized — invalid or missing API key
402	Payment required — upgrade to a paid plan

Response Fields

Field	Type	Description
`success`	boolean	Whether the request succeeded
`data`	object[]	Array of upserted vector results
`data[].id`	string	Stored vector ID

Notes

TTL behavior:

Omitted: Vector expires after 30 days (default)
null or 0: Vector never expires
60–7,776,000: Expires after specified seconds (values outside range are clamped)

Example

curl -X PUT 'https://catalyst-usw.agentuity.cloud/vector/products' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '[
  {
    "key": "chair-001",
    "document": "Comfortable office chair with lumbar support",
    "metadata": {
      "category": "furniture",
      "price": 299
    }
  }
]'

Get Vector

Fetch a vector by namespace and key.

GET/vector/{namespace}/{key}

https://catalyst-usw.agentuity.cloud/vector/{namespace}/{key}

Parameters

path

Name	Type	Required	Description
`namespace`	string	Yes	The namespace name
`key`	string	Yes	The vector key

Response

JSON response with vector data, metadata, similarity, and expiration fields.

Status	Description
200	Vector found and returned
401	Unauthorized
404	Vector not found

Response Fields

Field	Type	Description
`success`	boolean	Whether the request succeeded
`data`	object	The vector data object
`data.id`	string	Internal vector ID
`data.key`	string	Vector key
`data.document`	string	Original source document text (optional)
`data.embeddings`	number[]	Stored embeddings array (optional)
`data.metadata`	object	Stored metadata (optional)
`data.similarity`	number	Similarity score when relevant
`data.expiresAt`	string \| null	ISO 8601 expiration timestamp (optional)

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/vector/products/chair-001' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Search Vectors

Run semantic similarity search in a namespace.

POST/vector/search/{namespace}

https://catalyst-usw.agentuity.cloud/vector/search/{namespace}

Parameters

path

Name	Type	Required	Description
`namespace`	string	Yes	The namespace to search

Request Body

Search criteria and filters.

Field	Type	Description
`query`	string	The text query to search for in the vector storage. This will be converted to embeddings and used to find semantically similar documents.
`limit`	number	Maximum number of search results to return. If not specified, the server default will be used. (optional)
`similarity`	number	Minimum similarity threshold for results. Only vectors with similarity scores greater than or equal to this value will be returned. (optional)
`metadata`	object	Metadata filters to apply to the search. Only vectors whose metadata matches all specified key-value pairs will be included in results. (optional)

Response

JSON response containing matching vectors and similarity scores.

Status	Description
200	Search results returned
401	Unauthorized
404	Namespace not found (returns empty array)

Response Fields

Field	Type	Description
`success`	boolean	Whether the request succeeded
`data`	object[]	Array of matching vector results
`data[].id`	string	Vector ID
`data[].key`	string	Vector key
`data[].metadata`	object	Vector metadata (optional)
`data[].similarity`	number	Similarity score (0–1)
`data[].expiresAt`	string \| null	ISO 8601 expiration timestamp (optional)

Example

curl -X POST 'https://catalyst-usw.agentuity.cloud/vector/search/products' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "query": "comfortable seating for office",
  "limit": 5,
  "similarity": 0.7
}'

Delete Vector

Delete a single vector by key.

DELETE/vector/{namespace}/{key}

https://catalyst-usw.agentuity.cloud/vector/{namespace}/{key}

Parameters

path

Name	Type	Required	Description
`namespace`	string	Yes	The namespace name
`key`	string	Yes	The vector key to delete

Response

JSON response with deleted row count.

Status	Description
200	Delete operation completed
401	Unauthorized
404	Vector not found (returns 0)

Response Fields

Field	Type	Description
`success`	boolean	Whether the request succeeded
`data`	number	Number of deleted vectors

Example

curl -X DELETE 'https://catalyst-usw.agentuity.cloud/vector/products/chair-001' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

Delete Multiple Vectors

Delete multiple vectors by key. If no body is provided, deletes the entire namespace.

DELETE/vector/{namespace}

https://catalyst-usw.agentuity.cloud/vector/{namespace}

Parameters

path

Name	Type	Required	Description
`namespace`	string	Yes	The namespace name

Request Body

Optional JSON body specifying keys to delete.

Field	Type	Description
`keys`	string[]	Vector keys to delete

Response

JSON response with number of deleted vectors.

Status	Description
200	Delete operation completed
401	Unauthorized

Response Fields

Field	Type	Description
`success`	boolean	Whether the request succeeded
`data`	number	Number of deleted vectors

Example

curl -X DELETE 'https://catalyst-usw.agentuity.cloud/vector/products' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
  "keys": [
    "chair-001",
    "desk-001"
  ]
}'

Get Namespace Stats

Get aggregate stats for a namespace.

GET/vector/stats/{namespace}

https://catalyst-usw.agentuity.cloud/vector/stats/{namespace}

Parameters

path

Name	Type	Required	Description
`namespace`	string	Yes	The namespace name

Response

JSON object with namespace size and usage statistics.

Status	Description
200	Stats returned
401	Unauthorized
404	Namespace not found (returns zeros)

Response Fields

Field	Type	Description
`sum`	number	Total size in bytes
`count`	number	Number of vectors in the namespace
`createdAt`	number	Unix timestamp (milliseconds) when the namespace was created (optional)
`lastUsed`	number	Unix timestamp (milliseconds) when the namespace was last used (optional)
`sampledResults`	object	A sample of vectors in the namespace (up to 20) (optional)

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/vector/stats/products' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

List All Namespace Stats

List namespace stats with pagination, filtering, and sorting.

GET/vector/stats

https://catalyst-usw.agentuity.cloud/vector/stats

Parameters

query

Name	Type	Required	Description
`limit`	number	No	Maximum namespaces to return (default: 100, max: 1000)
`offset`	number	No	Offset for pagination
`sort`	string	No	Sort by `name`, `size`, `records`, `created`, or `lastUsed`
`direction`	string	No	Sort direction: `asc` or `desc`
`name`	string	No	Filter namespaces by name

Response

Paginated namespace stats response.

Status	Description
200	Stats returned
401	Unauthorized

Response Fields

Field	Type	Description
`namespaces`	object	Map of namespace names to their statistics
`total`	number	Total number of namespaces across all pages
`limit`	number	Number of namespaces requested per page
`offset`	number	Number of namespaces skipped
`hasMore`	boolean	Whether there are more namespaces available

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/vector/stats?limit=10&sort=size&direction=desc' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'

List Namespaces

List namespace names (up to 1000).

GET/vector/namespaces

https://catalyst-usw.agentuity.cloud/vector/namespaces

Response

JSON array of namespace names.

Status	Description
200	Namespace list returned
401	Unauthorized

Example

curl -X GET 'https://catalyst-usw.agentuity.cloud/vector/namespaces' \
  -H 'Authorization: Bearer $AGENTUITY_SDK_KEY'