Hadrian is experimental alpha software. Do not use in production.
Hadrian
API Reference

Vector stores

Create and manage vector stores for RAG (Retrieval Augmented Generation). Vector stores contain files that are chunked and embedded for semantic search.

Hadrian Extensions

The Vector Stores API is based on OpenAI's Vector Stores API with the following extensions:

Multi-Tenancy

  • owner_type, owner_id fields for organization/project/user ownership
  • Required in create requests and included in responses

Additional Fields

  • description: Human-readable description for vector stores
  • embedding_model: Configurable embedding model (default: text-embedding-3-small)
  • embedding_dimensions: Configurable vector dimensions (default: 1536)
  • updated_at: Modification timestamp
  • file_id: Reference to Files API in vector store files

Extension Endpoints

  • GET /v1/vector_stores/{id}/files/{file_id}/chunks: List chunks for debugging

Search Extensions

  • Request: threshold (similarity threshold), file_ids (file filter)
  • Response: chunk_id, vector_store_id, chunk_index for debugging

Schema Differences

  • Timestamps use ISO 8601 format (OpenAI uses Unix timestamps)
  • List responses use pagination object (OpenAI uses root-level first_id, last_id, has_more)
  • Search content is a string (OpenAI uses [{type, text}] array)

List vector stores

GET
/api/v1/vector_stores

Authorization

api_key
AuthorizationBearer <token>

API key authentication using Bearer token format

In: header

Query Parameters

owner_type?string|null

Hadrian Extension: Owner type for multi-tenancy (organization, team, project, or user). When omitted along with owner_id, returns all accessible vector stores.

owner_id?string|null

Hadrian Extension: Owner ID for multi-tenancy. When omitted along with owner_type, returns all accessible vector stores.

Formatuuid
limit?integer|null

Maximum number of vector stores to return (default: 20, max: 100)

Formatint64
Range1 <= value <= 100
order?null|SortOrder

Sort order by created_at timestamp (default: desc)

after?string|null

Cursor for forward pagination. Returns results after this object ID. Use the last_id from a previous response to get the next page.

before?string|null

Cursor for backward pagination. Returns results before this object ID. Use the first_id from a previous response to get the previous page.

Response Body

application/json

application/json

curl -X GET "https://loading/api/v1/vector_stores?after=vs_550e8400-e29b-41d4-a716-446655440000&before=vs_550e8400-e29b-41d4-a716-446655440000"
{
  "data": [
    {
      "created_at": "2019-08-24T14:15:22Z",
      "description": "string",
      "embedding_dimensions": 0,
      "embedding_model": "string",
      "expires_after": {},
      "expires_at": "2019-08-24T14:15:22Z",
      "file_counts": {
        "cancelled": 0,
        "completed": 0,
        "failed": 0,
        "in_progress": 0,
        "total": 0
      },
      "id": "vs_550e8400-e29b-41d4-a716-446655440000",
      "last_active_at": "2019-08-24T14:15:22Z",
      "metadata": {
        "property1": null,
        "property2": null
      },
      "name": "string",
      "object": "string",
      "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05",
      "owner_type": "organization",
      "status": "in_progress",
      "updated_at": "2019-08-24T14:15:22Z",
      "usage_bytes": 0
    }
  ],
  "first_id": "string",
  "has_more": true,
  "last_id": "string",
  "object": "string"
}
{
  "error": {
    "code": "budget_exceeded",
    "message": "Budget limit exceeded for monthly period",
    "param": null,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "invalid_request_error"
  }
}

Create a vector store

POST
/api/v1/vector_stores

Authorization

api_key
AuthorizationBearer <token>

API key authentication using Bearer token format

In: header

Request Body

application/json

chunking_strategy?null|
description?string|null

Description of the vector store

embedding_dimensions?integer

Hadrian Extension: Embedding dimensions (immutable after creation, default: 1536)

Formatint32
embedding_model?string

Hadrian Extension: Embedding model to use (immutable after creation, default: text-embedding-3-small)

expires_after?null|
file_ids?array<string>

A list of File IDs that the vector store should use (max 500). Files will be attached to the vector store after creation.

metadata?|null

Custom metadata (up to 16 key-value pairs, keys max 64 chars, string values max 512 chars)

name?string|null

Name of the vector store (optional, auto-generated if not provided)

owner*|||

Hadrian Extension: Owner of the vector store (required for multi-tenancy)

Response Body

application/json

application/json

application/json

curl -X POST "https://loading/api/v1/vector_stores" \  -H "Content-Type: application/json" \  -d '{    "owner": {      "organization_id": "7c60d51f-b44e-4682-87d6-449835ea4de6",      "type": "organization"    }  }'
{
  "created_at": "2019-08-24T14:15:22Z",
  "description": "string",
  "embedding_dimensions": 0,
  "embedding_model": "string",
  "expires_after": {},
  "expires_at": "2019-08-24T14:15:22Z",
  "file_counts": {
    "cancelled": 0,
    "completed": 0,
    "failed": 0,
    "in_progress": 0,
    "total": 0
  },
  "id": "vs_550e8400-e29b-41d4-a716-446655440000",
  "last_active_at": "2019-08-24T14:15:22Z",
  "metadata": {
    "property1": null,
    "property2": null
  },
  "name": "string",
  "object": "string",
  "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05",
  "owner_type": "organization",
  "status": "in_progress",
  "updated_at": "2019-08-24T14:15:22Z",
  "usage_bytes": 0
}
{
  "error": {
    "code": "budget_exceeded",
    "message": "Budget limit exceeded for monthly period",
    "param": null,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "invalid_request_error"
  }
}
{
  "error": {
    "code": "budget_exceeded",
    "message": "Budget limit exceeded for monthly period",
    "param": null,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "invalid_request_error"
  }
}

Get a vector store

GET
/api/v1/vector_stores/{vector_store_id}

Authorization

api_key
AuthorizationBearer <token>

API key authentication using Bearer token format

In: header

Path Parameters

vector_store_id*string

Vector store ID (e.g., vs_550e8400-e29b-41d4-a716-446655440000)

Response Body

application/json

application/json

curl -X GET "https://loading/api/v1/vector_stores/string"
{
  "created_at": "2019-08-24T14:15:22Z",
  "description": "string",
  "embedding_dimensions": 0,
  "embedding_model": "string",
  "expires_after": {},
  "expires_at": "2019-08-24T14:15:22Z",
  "file_counts": {
    "cancelled": 0,
    "completed": 0,
    "failed": 0,
    "in_progress": 0,
    "total": 0
  },
  "id": "vs_550e8400-e29b-41d4-a716-446655440000",
  "last_active_at": "2019-08-24T14:15:22Z",
  "metadata": {
    "property1": null,
    "property2": null
  },
  "name": "string",
  "object": "string",
  "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05",
  "owner_type": "organization",
  "status": "in_progress",
  "updated_at": "2019-08-24T14:15:22Z",
  "usage_bytes": 0
}
{
  "error": {
    "code": "budget_exceeded",
    "message": "Budget limit exceeded for monthly period",
    "param": null,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "invalid_request_error"
  }
}

Modify a vector store

POST
/api/v1/vector_stores/{vector_store_id}

Authorization

api_key
AuthorizationBearer <token>

API key authentication using Bearer token format

In: header

Path Parameters

vector_store_id*string

Vector store ID

Formatuuid

Request Body

application/json

description?string|null

Hadrian Extension: New description

expires_after?null|
metadata?|null

New metadata (replaces existing, up to 16 key-value pairs, keys max 64 chars, string values max 512 chars)

name?string|null

New name

Response Body

application/json

application/json

curl -X POST "https://loading/api/v1/vector_stores/497f6eca-6276-4993-bfeb-53cbbbba6f08" \  -H "Content-Type: application/json" \  -d '{}'
{
  "created_at": "2019-08-24T14:15:22Z",
  "description": "string",
  "embedding_dimensions": 0,
  "embedding_model": "string",
  "expires_after": {},
  "expires_at": "2019-08-24T14:15:22Z",
  "file_counts": {
    "cancelled": 0,
    "completed": 0,
    "failed": 0,
    "in_progress": 0,
    "total": 0
  },
  "id": "vs_550e8400-e29b-41d4-a716-446655440000",
  "last_active_at": "2019-08-24T14:15:22Z",
  "metadata": {
    "property1": null,
    "property2": null
  },
  "name": "string",
  "object": "string",
  "owner_id": "8826ee2e-7933-4665-aef2-2393f84a0d05",
  "owner_type": "organization",
  "status": "in_progress",
  "updated_at": "2019-08-24T14:15:22Z",
  "usage_bytes": 0
}
{
  "error": {
    "code": "budget_exceeded",
    "message": "Budget limit exceeded for monthly period",
    "param": null,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "invalid_request_error"
  }
}

Delete a vector store

DELETE
/api/v1/vector_stores/{vector_store_id}

Authorization

api_key
AuthorizationBearer <token>

API key authentication using Bearer token format

In: header

Path Parameters

vector_store_id*string

Vector store ID

Formatuuid

Response Body

application/json

application/json

curl -X DELETE "https://loading/api/v1/vector_stores/497f6eca-6276-4993-bfeb-53cbbbba6f08"
{
  "deleted": true,
  "id": "string",
  "object": "string"
}
{
  "error": {
    "code": "budget_exceeded",
    "message": "Budget limit exceeded for monthly period",
    "param": null,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "invalid_request_error"
  }
}

Create a file batch

POST
/api/v1/vector_stores/{vector_store_id}/file_batches

Authorization

api_key
AuthorizationBearer <token>

API key authentication using Bearer token format

In: header

Path Parameters

vector_store_id*string

Vector store ID

Formatuuid

Request Body

application/json

chunking_strategy?null|
file_ids*array<string>

File IDs to add to the batch

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://loading/api/v1/vector_stores/497f6eca-6276-4993-bfeb-53cbbbba6f08/file_batches" \  -H "Content-Type: application/json" \  -d '{    "file_ids": [      "497f6eca-6276-4993-bfeb-53cbbbba6f08"    ]  }'
{
  "created_at": 0,
  "file_counts": {
    "cancelled": 0,
    "completed": 0,
    "failed": 0,
    "in_progress": 0,
    "total": 0
  },
  "id": "string",
  "object": "string",
  "status": "string",
  "vector_store_id": "string"
}
{
  "error": {
    "code": "budget_exceeded",
    "message": "Budget limit exceeded for monthly period",
    "param": null,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "invalid_request_error"
  }
}
{
  "error": {
    "code": "budget_exceeded",
    "message": "Budget limit exceeded for monthly period",
    "param": null,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "invalid_request_error"
  }
}
{
  "error": {
    "code": "budget_exceeded",
    "message": "Budget limit exceeded for monthly period",
    "param": null,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "invalid_request_error"
  }
}
{
  "error": {
    "code": "budget_exceeded",
    "message": "Budget limit exceeded for monthly period",
    "param": null,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "invalid_request_error"
  }
}

Get a file batch

GET
/api/v1/vector_stores/{vector_store_id}/file_batches/{batch_id}

Authorization

api_key
AuthorizationBearer <token>

API key authentication using Bearer token format

In: header

Path Parameters

vector_store_id*string

Vector store ID

Formatuuid
batch_id*string

File batch ID

Response Body

application/json

curl -X GET "https://loading/api/v1/vector_stores/497f6eca-6276-4993-bfeb-53cbbbba6f08/file_batches/string"
{
  "error": {
    "code": "budget_exceeded",
    "message": "Budget limit exceeded for monthly period",
    "param": null,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "invalid_request_error"
  }
}

Cancel a file batch

DELETE
/api/v1/vector_stores/{vector_store_id}/file_batches/{batch_id}

Authorization

api_key
AuthorizationBearer <token>

API key authentication using Bearer token format

In: header

Path Parameters

vector_store_id*string

Vector store ID

Formatuuid
batch_id*string

File batch ID

Response Body

application/json

curl -X DELETE "https://loading/api/v1/vector_stores/497f6eca-6276-4993-bfeb-53cbbbba6f08/file_batches/string"
{
  "error": {
    "code": "budget_exceeded",
    "message": "Budget limit exceeded for monthly period",
    "param": null,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "invalid_request_error"
  }
}

List files in a batch

GET
/api/v1/vector_stores/{vector_store_id}/file_batches/{batch_id}/files

Authorization

api_key
AuthorizationBearer <token>

API key authentication using Bearer token format

In: header

Path Parameters

vector_store_id*string

Vector store ID

Formatuuid
batch_id*string

File batch ID

Response Body

application/json

curl -X GET "https://loading/api/v1/vector_stores/497f6eca-6276-4993-bfeb-53cbbbba6f08/file_batches/string/files"
{
  "error": {
    "code": "budget_exceeded",
    "message": "Budget limit exceeded for monthly period",
    "param": null,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "invalid_request_error"
  }
}

List vector store files

GET
/api/v1/vector_stores/{vector_store_id}/files

Authorization

api_key
AuthorizationBearer <token>

API key authentication using Bearer token format

In: header

Path Parameters

vector_store_id*string

Vector store ID

Formatuuid

Query Parameters

limit?integer|null

Maximum number of files to return (default: 20, max: 100)

Formatint64
Range1 <= value <= 100
order?null|SortOrder

Sort order by created_at timestamp (default: desc)

after?string|null

Cursor for forward pagination. Returns results after this file ID.

before?string|null

Cursor for backward pagination. Returns results before this file ID.

filter?string|null

Filter by status (in_progress, completed, failed, cancelled)

Response Body

application/json

application/json

curl -X GET "https://loading/api/v1/vector_stores/497f6eca-6276-4993-bfeb-53cbbbba6f08/files?after=vsf_550e8400-e29b-41d4-a716-446655440000&before=vsf_550e8400-e29b-41d4-a716-446655440000"
{
  "data": [
    {
      "attributes": {
        "property1": null,
        "property2": null
      },
      "chunking_strategy": {},
      "created_at": "2019-08-24T14:15:22Z",
      "id": "file-550e8400-e29b-41d4-a716-446655440000",
      "last_error": {},
      "object": "string",
      "status": "in_progress",
      "updated_at": "2019-08-24T14:15:22Z",
      "usage_bytes": 0,
      "vector_store_id": "vs_550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "first_id": "string",
  "has_more": true,
  "last_id": "string",
  "object": "string"
}
{
  "error": {
    "code": "budget_exceeded",
    "message": "Budget limit exceeded for monthly period",
    "param": null,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "invalid_request_error"
  }
}

Create a vector store file

POST
/api/v1/vector_stores/{vector_store_id}/files

Authorization

api_key
AuthorizationBearer <token>

API key authentication using Bearer token format

In: header

Path Parameters

vector_store_id*string

Vector store ID

Formatuuid

Request Body

application/json

chunking_strategy?null|
file_id*string

The ID of the file to add (from the Files API)

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://loading/api/v1/vector_stores/497f6eca-6276-4993-bfeb-53cbbbba6f08/files" \  -H "Content-Type: application/json" \  -d '{    "file_id": "file-550e8400-e29b-41d4-a716-446655440000"  }'
{
  "attributes": {
    "property1": null,
    "property2": null
  },
  "chunking_strategy": {},
  "created_at": "2019-08-24T14:15:22Z",
  "id": "file-550e8400-e29b-41d4-a716-446655440000",
  "last_error": {},
  "object": "string",
  "status": "in_progress",
  "updated_at": "2019-08-24T14:15:22Z",
  "usage_bytes": 0,
  "vector_store_id": "vs_550e8400-e29b-41d4-a716-446655440000"
}
{
  "attributes": {
    "property1": null,
    "property2": null
  },
  "chunking_strategy": {},
  "created_at": "2019-08-24T14:15:22Z",
  "id": "file-550e8400-e29b-41d4-a716-446655440000",
  "last_error": {},
  "object": "string",
  "status": "in_progress",
  "updated_at": "2019-08-24T14:15:22Z",
  "usage_bytes": 0,
  "vector_store_id": "vs_550e8400-e29b-41d4-a716-446655440000"
}
{
  "error": {
    "code": "budget_exceeded",
    "message": "Budget limit exceeded for monthly period",
    "param": null,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "invalid_request_error"
  }
}
{
  "error": {
    "code": "budget_exceeded",
    "message": "Budget limit exceeded for monthly period",
    "param": null,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "invalid_request_error"
  }
}
{
  "error": {
    "code": "budget_exceeded",
    "message": "Budget limit exceeded for monthly period",
    "param": null,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "invalid_request_error"
  }
}
{
  "error": {
    "code": "budget_exceeded",
    "message": "Budget limit exceeded for monthly period",
    "param": null,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "invalid_request_error"
  }
}

Get a vector store file

GET
/api/v1/vector_stores/{vector_store_id}/files/{file_id}

Authorization

api_key
AuthorizationBearer <token>

API key authentication using Bearer token format

In: header

Path Parameters

vector_store_id*string

Vector store ID

Formatuuid
file_id*string

Vector store file ID

Formatuuid

Response Body

application/json

application/json

curl -X GET "https://loading/api/v1/vector_stores/497f6eca-6276-4993-bfeb-53cbbbba6f08/files/497f6eca-6276-4993-bfeb-53cbbbba6f08"
{
  "attributes": {
    "property1": null,
    "property2": null
  },
  "chunking_strategy": {},
  "created_at": "2019-08-24T14:15:22Z",
  "id": "file-550e8400-e29b-41d4-a716-446655440000",
  "last_error": {},
  "object": "string",
  "status": "in_progress",
  "updated_at": "2019-08-24T14:15:22Z",
  "usage_bytes": 0,
  "vector_store_id": "vs_550e8400-e29b-41d4-a716-446655440000"
}
{
  "error": {
    "code": "budget_exceeded",
    "message": "Budget limit exceeded for monthly period",
    "param": null,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "invalid_request_error"
  }
}

Delete a vector store file

DELETE
/api/v1/vector_stores/{vector_store_id}/files/{file_id}

Authorization

api_key
AuthorizationBearer <token>

API key authentication using Bearer token format

In: header

Path Parameters

vector_store_id*string

Vector store ID

Formatuuid
file_id*string

Vector store file ID

Formatuuid

Response Body

application/json

application/json

curl -X DELETE "https://loading/api/v1/vector_stores/497f6eca-6276-4993-bfeb-53cbbbba6f08/files/497f6eca-6276-4993-bfeb-53cbbbba6f08"
{
  "deleted": true,
  "id": "string",
  "object": "string"
}
{
  "error": {
    "code": "budget_exceeded",
    "message": "Budget limit exceeded for monthly period",
    "param": null,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "invalid_request_error"
  }
}

List chunks for a file [Hadrian Extension]

GET
/api/v1/vector_stores/{vector_store_id}/files/{file_id}/chunks

Authorization

api_key
AuthorizationBearer <token>

API key authentication using Bearer token format

In: header

Path Parameters

vector_store_id*string

Vector store ID

Formatuuid
file_id*string

Vector store file ID

Formatuuid

Response Body

application/json

application/json

application/json

curl -X GET "https://loading/api/v1/vector_stores/497f6eca-6276-4993-bfeb-53cbbbba6f08/files/497f6eca-6276-4993-bfeb-53cbbbba6f08/chunks"
{
  "data": [
    {
      "char_end": 0,
      "char_start": 0,
      "chunk_index": 0,
      "content": "string",
      "created_at": 0,
      "file_id": "file-550e8400-e29b-41d4-a716-446655440000",
      "id": "chunk_550e8400-e29b-41d4-a716-446655440000",
      "metadata": null,
      "object": "string",
      "token_count": 0,
      "vector_store_id": "vs_550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "object": "string",
  "pagination": {
    "has_more": true,
    "limit": 100,
    "next_cursor": "MTczMzU4MDgwMDAwMDphYmMxMjM0NS02Nzg5LTAxMjMtNDU2Ny0wMTIzNDU2Nzg5YWI",
    "prev_cursor": "string"
  }
}
{
  "error": {
    "code": "budget_exceeded",
    "message": "Budget limit exceeded for monthly period",
    "param": null,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "invalid_request_error"
  }
}
{
  "error": {
    "code": "budget_exceeded",
    "message": "Budget limit exceeded for monthly period",
    "param": null,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "invalid_request_error"
  }
}

Search vector store

POST
/api/v1/vector_stores/{vector_store_id}/search

Authorization

api_key
AuthorizationBearer <token>

API key authentication using Bearer token format

In: header

Path Parameters

vector_store_id*string

Vector store ID

Formatuuid

Request Body

application/json

filters?null|
max_num_results?integer|null

Maximum number of results to return (default: 10, max: 50).

Range0 <= value
query*string

The search query text.

ranking_options?null|

Response Body

application/json

application/json

application/json

application/json

curl -X POST "https://loading/api/v1/vector_stores/497f6eca-6276-4993-bfeb-53cbbbba6f08/search" \  -H "Content-Type: application/json" \  -d '{    "query": "string"  }'
{
  "data": [
    {
      "chunk_id": "chunk_550e8400-e29b-41d4-a716-446655440000",
      "chunk_index": 0,
      "content": "string",
      "file_id": "file-550e8400-e29b-41d4-a716-446655440000",
      "filename": "string",
      "metadata": null,
      "object": "string",
      "score": 0.1,
      "vector_store_id": "vs_550e8400-e29b-41d4-a716-446655440000"
    }
  ],
  "object": "string",
  "query": "string"
}
{
  "error": {
    "code": "budget_exceeded",
    "message": "Budget limit exceeded for monthly period",
    "param": null,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "invalid_request_error"
  }
}
{
  "error": {
    "code": "budget_exceeded",
    "message": "Budget limit exceeded for monthly period",
    "param": null,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "invalid_request_error"
  }
}
{
  "error": {
    "code": "budget_exceeded",
    "message": "Budget limit exceeded for monthly period",
    "param": null,
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "type": "invalid_request_error"
  }
}

Users

Previous Page

Deployment

Production deployment guides for Hadrian Gateway