API Documentation

Getting Started

The AI Data SDK REST API provides access to all SDK capabilities through HTTP endpoints. The API follows REST principles and returns JSON responses.

Authentication

All API requests require authentication using an API key or JWT token. Include your API key in the request headers as follows:

Base URL

All API endpoints use the following base URL:

Create Embeddings

Generate vector embeddings from text inputs that can be used for search, classification, clustering, and more.

Request Parameters

Parameter	Type	Description	Required
texts	array	Array of strings to convert into embeddings	Yes
model	string	The embedding model to use. Defaults to system configuration.	No
metadata	array	Array of metadata objects to associate with each text	No

Example Request

{
  "texts": ["Your text string goes here"],
  "model": "text-embedding-ada-002"
}

Example Response

{
  "embeddings": [[0.0023063174, -0.009358601, ...]],
  "model": "text-embedding-ada-002",
  "dimensions": 1536,
  "processing_time_ms": 245
}

List Embeddings

List stored embeddings for the authenticated user.

Example Response

{
  "embeddings": [
    {
      "id": "emb_123",
      "text": "Example text",
      "model": "text-embedding-ada-002",
      "created_at": "2025-01-01T00:00:00Z"
    }
  ],
  "count": 1
}

Delete Embedding

Delete a specific embedding. Users can only delete their own embeddings, unless they are admins.

Example Response

{
  "message": "Embedding emb_123 deleted successfully"
}

Search

Perform semantic search using vector embeddings to find relevant content based on query text.

Request Parameters

Parameter	Type	Description	Required
query	string	The search query text	Yes (if embedding not provided)
embedding	array	Pre-computed query embedding vector	Yes (if query not provided)
top_k	integer	Number of results to return (max 100)	No
filters	object	Metadata filters to apply to search results	No

Example Request

{
  "query": "machine learning applications",
  "top_k": 5,
  "filters": { "source": "research_paper" }
}

Example Response

{
  "results": [
    {
      "id": "doc_456",
      "text": "Machine learning applications in healthcare",
      "metadata": { "source": "research_paper", "date": "2024-11-05" },
      "score": 0.92
    }
  ],
  "query_id": "q_12345",
  "processing_time_ms": 58,
  "total_documents": 1000
}

The PII Services API provides endpoints for detecting and anonymizing personally identifiable information (PII) in text content.

Detect PII

Detect and identify personally identifiable information (PII) in text content.

Request Parameters

Parameter	Type	Description	Required
text	string	Text to scan for PII	Yes
pii_types	array	Specific PII types to detect	No
mask_pii	boolean	Whether to return masked version of the text	No
mask_type	string	Masking type: type, redact, partial, generic	No
preserve_length	boolean	Whether to preserve length in masking	No
resolve_overlaps	boolean	Whether to resolve overlapping entities	No

Example Request

{
  "text": "Contact John Doe at john.doe@example.com or 555-123-4567",
  "mask_pii": true,
  "mask_type": "type"
}

Example Response

{
  "masked_text": "Contact John Doe at [EMAIL] or [PHONE]",
  "pii_detected": [
    {
      "type": "email",
      "text": "john.doe@example.com",
      "start": 15,
      "end": 35,
      "confidence": 0.99
    },
    {
      "type": "phone",
      "text": "555-123-4567",
      "start": 39,
      "end": 51,
      "confidence": 0.95
    }
  ],
  "total_pii_count": 2,
  "pii_type_counts": {
    "email": 1,
    "phone": 1
  },
  "processing_time_ms": 45
}

Anonymize PII

Advanced PII anonymization with consistent replacements of personally identifiable information in text.

Request Parameters

Parameter	Type	Description	Required
text	string	Text to anonymize	Yes
pii_types	array	Specific PII types to anonymize	No
replacement_map	object	Pre-defined replacements for specific PII values	No
consistent_replacements	boolean	Whether to use consistent replacements throughout the text	No
resolve_overlaps	boolean	Whether to resolve overlapping entities	No

Example Request

{
  "text": "John Smith called from 555-123-4567 and said John needs his records updated.",
  "consistent_replacements": true
}

Example Response

{
  "anonymized_text": "Alex Johnson called from 555-987-6543 and said Alex needs his records updated.",
  "pii_detected": [
    {
      "type": "name",
      "text": "John Smith",
      "start": 0,
      "end": 10,
      "confidence": 0.95
    },
    {
      "type": "phone",
      "text": "555-123-4567",
      "start": 22,
      "end": 34,
      "confidence": 0.99
    },
    {
      "type": "name",
      "text": "John",
      "start": 44,
      "end": 48,
      "confidence": 0.90
    }
  ],
  "replacement_map": {
    "John Smith": "Alex Johnson",
    "John": "Alex",
    "555-123-4567": "555-987-6543"
  },
  "total_pii_count": 3,
  "pii_type_counts": {
    "name": 2,
    "phone": 1
  },
  "processing_time_ms": 67
}

Submit Feedback

Submit user feedback on search results to improve system performance.

Request Parameters

Parameter	Type	Description	Required
query_id	string	The ID of the query being rated	Yes
result_id	string	The ID of the result being rated	Yes
rating	integer	User rating score (1-5)	Yes
comments	string	Optional user comment	No

Example Request

{
  "query_id": "q_12345",
  "result_id": "doc_456",
  "rating": 4,
  "comments": "Results were relevant but could be better ordered"
}

Example Response

{
  "feedback_id": "fb_7890",
  "timestamp": "2025-05-11T09:45:22Z"
}