API Overview

API Architecture

The Structify API is a RESTful service that provides endpoints for:

Dataset Management: Create and configure dataset schemas
Entity Operations: Add, update, and query entities (nodes)
Relationship Management: Connect entities with typed relationships
Document Processing: Upload and structure unstructured data
Job Management: Track asynchronous processing tasks
Search & Query: Natural language and relationship-based search

Core Concepts

Datasets

A dataset is a container for your structured data. Each dataset has:

A unique name
A schema defining entity types and properties
Tables for different entity types
Relationships between entities

# Create a dataset
dataset = client.datasets.create(
    name="CompanyData",
    description="Company information and relationships"
)

Entities

Entities are the records in your dataset. Each entity:

Belongs to a specific table (entity type)
Has properties defined by the schema
Can be connected to other entities via relationships

# Add an entity
entity = client.entities.add(
    dataset_name="CompanyData",
    table_name="Company",
    entity={
        "Name": "Acme Corp",
        "Industry": "Technology"
    }
)

Relationships

Relationships connect entities in your dataset. They:

Have a type (e.g., “Owns”, “Partners With”)
Can have properties
Are directional (source → target)

# Create a relationship
client.entities.add_relationship(
    dataset_name="CompanyData",
    source_entity_id=company_id,
    target_entity_id=subsidiary_id,
    relationship_name="Owns",
    properties={"percentage": 100}
)

Jobs

Many operations are asynchronous and return a job. Jobs:

Track the progress of long-running operations
Can be queried for status
Return results when complete

# Start a job
job = client.documents.structure(
    document_id=doc_id,
    dataset_name="CompanyData"
)

# Check status
status = client.jobs.get(job_id=job.id)
if status.status == "completed":
    print("Job finished!")

Authentication

All API requests require authentication via API key:

from structify import Structify

# Using environment variable (recommended)
client = Structify()  # Uses STRUCTIFY_API_TOKEN

# Or explicit API key
client = Structify(api_key="your_api_key")

Rate Limits

API requests are rate limited based on your plan:

Plan	Requests/min	Concurrent Jobs
Free	60	2
Pro	600	10
Enterprise	Custom	Custom

Error Handling

The API uses standard HTTP status codes:

from structify import BadRequestError, NotFoundError

try:
    entity = client.entities.get(entity_id="invalid")
except NotFoundError as e:
    print(f"Entity not found: {e}")
except BadRequestError as e:
    print(f"Invalid request: {e}")

Pagination

List endpoints support pagination:

# Get paginated results
jobs = client.jobs.list(
    limit=10,
    offset=20
)

for job in jobs:
    print(f"Job {job.id}: {job.status}")

Async Operations

For better performance, use the async client:

from structify import AsyncStructify
import asyncio

async def process_documents():
    client = AsyncStructify()

    # Upload multiple documents concurrently
    tasks = [
        client.documents.upload(file_path=f"doc{i}.pdf")
        for i in range(10)
    ]
    results = await asyncio.gather(*tasks)
    return results

WebSocket Events

Real-time updates are available via WebSocket:

# Subscribe to job events
async def listen_for_updates():
    async with client.websocket() as ws:
        async for event in ws:
            if event.type == "job.completed":
                print(f"Job {event.job_id} completed")

Best Practices

Use Environment Variables

Store API keys in environment variables, never in code

Batch Operations

Use batch endpoints when processing multiple items

Handle Rate Limits

Implement exponential backoff for rate limit errors

Monitor Jobs

Poll job status or use WebSockets for real-time updates

Cache Results

Cache frequently accessed data to reduce API calls

Next Steps

API Reference

Detailed endpoint documentation

Examples

Real-world usage examples

Get Started

Tips and Tricks

Connectors

Deployments

Core Concepts

Schema Cookbook

Examples

API Architecture

Core Concepts

Datasets

Entities

Relationships

Jobs

Authentication

Rate Limits

Error Handling

Async Operations

WebSocket Events

Best Practices

Next Steps

API Reference

Examples

​API Architecture

​Core Concepts

​Datasets

​Entities

​Relationships

​Jobs

​Authentication

​Rate Limits

​Error Handling

​Pagination

​Async Operations

​WebSocket Events

​Best Practices

​Next Steps

API Reference

Examples

API Architecture

Core Concepts

Datasets

Entities

Relationships

Jobs

Authentication

Rate Limits

Error Handling

Pagination

Async Operations

WebSocket Events

Best Practices

Next Steps