Novek Logo
Demo
Developer Resources

api developer guide

NovekAI API & Developer Guide

Overview

The NovekAI API provides developers with programmatic access to the platform's document intelligence capabilities. This guide outlines the available APIs, authentication methods, request/response formats, and best practices for integration.

API Philosophy

The NovekAI API is designed around the following principles:

  1. RESTful Design: Our APIs follow REST principles with resource-oriented URLs, standard HTTP methods, and appropriate status codes.

  2. Comprehensive Capabilities: The API provides access to all core platform capabilities, enabling full programmatic control.

  3. Developer Experience: We prioritize clear documentation, consistent patterns, and helpful error messages to ensure a positive developer experience.

  4. Enterprise Readiness: Our APIs include robust authentication, rate limiting, and monitoring capabilities to meet enterprise requirements.

  5. Extensibility: The platform is designed to be extended and customized through the API, enabling integration with your unique workflows and systems.

Authentication

Novek.ai supports multiple authentication methods to accommodate different security requirements:

API Keys

For server-to-server integrations, API keys provide a simple authentication mechanism.

GET /api/v1/documents
Authorization: ApiKey YOUR_API_KEY

API keys can be generated and managed through the NovekAI administration portal. Each key can be assigned specific permissions and rate limits.

OAuth 2.0

For applications acting on behalf of users, OAuth 2.0 provides a secure delegation framework.

GET /api/v1/documents
Authorization: Bearer YOUR_ACCESS_TOKEN

Novek.ai supports the following OAuth 2.0 flows:

  • Authorization Code Flow: For web applications
  • PKCE Extension: For mobile and single-page applications
  • Client Credentials Flow: For server-to-server API access

SAML and OpenID Connect

For enterprise deployments with existing identity providers, NovekAI supports SAML 2.0 and OpenID Connect integration.

API Endpoints

The NovekAI API is organized into the following main categories:

Document Management API

Manage documents within the NovekAI platform.

  • GET /api/v1/documents: List documents with filtering and pagination
  • POST /api/v1/documents: Upload a new document
  • GET /api/v1/documents/{id}: Retrieve document metadata
  • PUT /api/v1/documents/{id}: Update document metadata
  • DELETE /api/v1/documents/{id}: Delete a document
  • GET /api/v1/documents/{id}/content: Download document content
  • GET /api/v1/documents/{id}/versions: List document versions
  • POST /api/v1/documents/{id}/versions: Create a new document version

Search API

Search across documents using various query types.

  • POST /api/v1/search: Perform a search with advanced options
  • POST /api/v1/search/semantic: Perform a semantic search
  • POST /api/v1/search/natural-language: Perform a natural language search
  • GET /api/v1/search/saved: List saved searches
  • POST /api/v1/search/saved: Create a saved search
  • GET /api/v1/search/saved/{id}: Retrieve a saved search
  • PUT /api/v1/search/saved/{id}: Update a saved search
  • DELETE /api/v1/search/saved/{id}: Delete a saved search

AI Assistant API

Interact with the NovekAI AI assistant.

  • POST /api/v1/assistant/chat: Send a message to the AI assistant
  • POST /api/v1/assistant/document-qa: Ask a question about specific documents
  • POST /api/v1/assistant/extract: Extract structured information from documents
  • GET /api/v1/assistant/conversations: List assistant conversations
  • GET /api/v1/assistant/conversations/{id}: Retrieve a specific conversation
  • DELETE /api/v1/assistant/conversations/{id}: Delete a conversation

Workflow API

Manage workflows and tasks within the platform.

  • GET /api/v1/workflows: List available workflows
  • POST /api/v1/workflows/{id}/instances: Start a new workflow instance
  • GET /api/v1/workflows/instances: List workflow instances
  • GET /api/v1/workflows/instances/{id}: Get workflow instance details
  • GET /api/v1/tasks: List tasks assigned to the current user
  • GET /api/v1/tasks/{id}: Get task details
  • POST /api/v1/tasks/{id}/complete: Complete a task

Analytics API

Access analytics and reporting data.

  • GET /api/v1/analytics/documents: Get document analytics
  • GET /api/v1/analytics/users: Get user activity analytics
  • GET /api/v1/analytics/search: Get search analytics
  • GET /api/v1/analytics/workflows: Get workflow analytics
  • POST /api/v1/analytics/custom: Run a custom analytics query

Administration API

Manage users, roles, and system settings.

  • GET /api/v1/users: List users
  • POST /api/v1/users: Create a new user
  • GET /api/v1/users/{id}: Get user details
  • PUT /api/v1/users/{id}: Update a user
  • DELETE /api/v1/users/{id}: Delete a user
  • GET /api/v1/roles: List roles
  • POST /api/v1/roles: Create a new role
  • GET /api/v1/settings: Get system settings
  • PUT /api/v1/settings: Update system settings

Request and Response Formats

Request Format

API requests should be formatted according to the following guidelines:

  • Use JSON for request bodies
  • Set the Content-Type header to application/json
  • For file uploads, use multipart/form-data
  • Include the Accept header with the desired response format

Example request:

POST /api/v1/documents HTTP/1.1
Host: api.novek.ai
Authorization: ApiKey YOUR_API_KEY
Content-Type: application/json
Accept: application/json

{
  "title": "Equipment Manual",
  "description": "Technical manual for pump system",
  "metadata": {
    "equipment_type": "pump",
    "manufacturer": "FlowTech",
    "model_number": "FT-3000"
  },
  "tags": ["technical", "equipment", "manual"]
}

Response Format

API responses follow a consistent format:

  • All responses include a status field indicating success or failure
  • Successful responses include a data field with the requested information
  • Error responses include an error field with details about the error
  • Paginated responses include pagination information

Example successful response:

{
  "status": "success",
  "data": {
    "id": "doc-123456",
    "title": "Equipment Manual",
    "description": "Technical manual for pump system",
    "metadata": {
      "equipment_type": "pump",
      "manufacturer": "FlowTech",
      "model_number": "FT-3000"
    },
    "tags": ["technical", "equipment", "manual"],
    "created_at": "2023-06-15T10:30:00Z",
    "updated_at": "2023-06-15T10:30:00Z"
  }
}

Example error response:

{
  "status": "error",
  "error": {
    "code": "invalid_request",
    "message": "The request was invalid",
    "details": [{
      "field": "title",
      "message": "Title is required"
    }]
  }
}

Example paginated response:

{
  "status": "success",
  "data": [
    { /* document 1 */ },
    { /* document 2 */ }
  ],
  "pagination": {
    "total": 157,
    "page": 1,
    "per_page": 10,
    "pages": 16,
    "next": "/api/v1/documents?page=2&per_page=10",
    "prev": null
  }
}

Pagination

For endpoints that return collections of resources, NovekAI supports pagination through the following query parameters:

  • page: The page number to retrieve (default: 1)
  • per_page: The number of items per page (default: 10, max: 100)

Paginated responses include a pagination object with the following fields:

  • total: Total number of items
  • page: Current page number
  • per_page: Number of items per page
  • pages: Total number of pages
  • next: URL for the next page (null if on last page)
  • prev: URL for the previous page (null if on first page)

Filtering and Sorting

Many endpoints support filtering and sorting through query parameters:

Filtering

Filters can be applied using the filter parameter with field-specific conditions:

GET /api/v1/documents?filter[metadata.equipment_type]=pump&filter[tags]=technical

Complex filters can be created using the q parameter with a query string:

GET /api/v1/documents?q=metadata.equipment_type:pump AND tags:technical

Sorting

Results can be sorted using the sort parameter:

GET /api/v1/documents?sort=created_at:desc

Multiple sort fields can be specified by separating them with commas:

GET /api/v1/documents?sort=metadata.equipment_type:asc,created_at:desc

Error Handling

Novek.ai uses standard HTTP status codes to indicate the success or failure of API requests:

  • 200 OK: The request was successful
  • 201 Created: The resource was successfully created
  • 204 No Content: The request was successful but returns no content
  • 400 Bad Request: The request was invalid
  • 401 Unauthorized: Authentication is required or failed
  • 403 Forbidden: The authenticated user lacks permission
  • 404 Not Found: The requested resource was not found
  • 409 Conflict: The request conflicts with the current state
  • 422 Unprocessable Entity: The request was well-formed but invalid
  • 429 Too Many Requests: Rate limit exceeded
  • 500 Internal Server Error: An unexpected error occurred

Error responses include detailed information to help diagnose and resolve issues:

{
  "status": "error",
  "error": {
    "code": "rate_limit_exceeded",
    "message": "API rate limit exceeded",
    "details": {
      "limit": 100,
      "remaining": 0,
      "reset": "2023-06-15T11:00:00Z"
    }
  }
}

Rate Limiting

To ensure fair usage and system stability, NovekAI implements rate limiting on API requests. Rate limits are applied per API key or user and vary based on the endpoint and subscription tier.

Rate limit information is included in the response headers:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1623758400

When a rate limit is exceeded, the API returns a 429 Too Many Requests response with information about when the limit will reset.

Webhooks

Novek.ai supports webhooks for real-time notifications about platform events. Webhooks can be configured through the administration portal or the API.

Available Events

  • document.created: A new document was created
  • document.updated: A document was updated
  • document.deleted: A document was deleted
  • workflow.started: A workflow was started
  • workflow.completed: A workflow was completed
  • task.assigned: A task was assigned
  • task.completed: A task was completed

Webhook Payload

Webhook payloads include information about the event and the affected resources:

{
  "event": "document.created",
  "timestamp": "2023-06-15T10:30:00Z",
  "data": {
    "id": "doc-123456",
    "title": "Equipment Manual",
    "created_by": "user-789012",
    "created_at": "2023-06-15T10:30:00Z"
  }
}

Webhook Security

To verify that webhook requests are coming from Novek.ai, each request includes a signature header:

X-Novek-Signature: sha256=5257a869e7bdf3ecf7f1991ef609c11096a6d099543f6c1f3e60f9895180123a

The signature is generated using HMAC-SHA256 with your webhook secret as the key and the request body as the message.

SDKs and Client Libraries

Novek.ai provides official SDKs for popular programming languages to simplify API integration:

JavaScript/TypeScript

npm install @novek/api-client

import { NovekClient } from '@novek/api-client';

const client = new NovekClient({
  apiKey: 'YOUR_API_KEY'
});

async function searchDocuments() {
  const results = await client.search.semantic({
    query: 'pump maintenance procedures',
    filters: {
      'metadata.equipment_type': 'pump'
    }
  });
  
  console.log(results);
}

searchDocuments();

Python

pip install novek-api-client

from novek import NovekClient

client = NovekClient(api_key='YOUR_API_KEY')

def search_documents():
    results = client.search.semantic(
        query='pump maintenance procedures',
        filters={
            'metadata.equipment_type': 'pump'
        }
    )
    
    print(results)

search_documents()

Java

<dependency>
  <groupId>ai.novek</groupId>
  <artifactId>api-client</artifactId>
  <version>1.0.0</version>
</dependency>

import ai.novek.client.NovekClient;
import ai.novek.client.models.SearchRequest;
import ai.novek.client.models.SearchResponse;

public class SearchExample {
    public static void main(String[] args) {
        NovekClient client = new NovekClient("YOUR_API_KEY");
        
        SearchRequest request = new SearchRequest.Builder()
            .query("pump maintenance procedures")
            .addFilter("metadata.equipment_type", "pump")
            .build();
        
        SearchResponse response = client.search().semantic(request);
        System.out.println(response);
    }
}

C#

Install-Package Novek.ApiClient

using Novek.ApiClient;
using Novek.ApiClient.Models;

var client = new NovekClient("YOUR_API_KEY");

var request = new SearchRequest
{
    Query = "pump maintenance procedures",
    Filters = new Dictionary<string, string>
    {
        { "metadata.equipment_type", "pump" }
    }
};

var response = await client.Search.SemanticAsync(request);
Console.WriteLine(response);

Integration Patterns

Novek.ai can be integrated with your applications and systems in several ways:

Direct API Integration

For custom applications, direct API integration provides the most flexibility. Use our SDKs or make HTTP requests directly to the API endpoints.

Embedded UI Components

For web applications, NovekAI provides embeddable UI components that can be integrated into your application:

<script src="https://cdn.novek.ai/embed.js"></script>

<div id="novek-search"></div>

<script>
  Novek.initialize({
    apiKey: 'YOUR_API_KEY',
    container: '#novek-search',
    component: 'search',
    options: {
      placeholder: 'Search technical documents...',
      filters: {
        'metadata.equipment_type': 'pump'
      }
    }
  });
</script>

Workflow Automation

For business process integration, NovekAI workflows can be triggered via API or integrated with workflow automation platforms:

  • Zapier Integration: Connect NovekAI with 3,000+ applications
  • Microsoft Power Automate: Create automated workflows with NovekAI actions
  • Custom Workflow Triggers: Trigger NovekAI workflows from external events

Data Integration

For data synchronization scenarios, NovekAI provides several options:

  • Batch Import/Export API: For bulk data operations
  • Change Data Capture: For real-time synchronization
  • ETL Connectors: For integration with data pipelines

Security Best Practices

When integrating with the NovekAI API, follow these security best practices:

API Key Management

  • Store API keys securely, never in client-side code
  • Use environment variables or secrets management services
  • Rotate API keys periodically
  • Use separate API keys for different environments (development, staging, production)

Access Control

  • Apply the principle of least privilege when assigning API key permissions
  • Use OAuth 2.0 for user-specific actions rather than API keys
  • Implement proper authorization checks in your application

Data Protection

  • Use HTTPS for all API requests
  • Minimize sensitive data in request parameters (use request body instead)
  • Implement proper error handling to avoid exposing sensitive information

Monitoring and Logging

  • Monitor API usage for unusual patterns
  • Log API requests and responses for audit purposes
  • Set up alerts for API errors and rate limit warnings

Performance Optimization

To ensure optimal performance when integrating with the NovekAI API:

Caching

  • Cache frequently accessed resources
  • Respect cache control headers in API responses
  • Implement conditional requests using ETags

Batch Operations

  • Use batch endpoints for multiple operations
  • Combine related requests when possible
  • Implement pagination for large result sets

Asynchronous Processing

  • Use webhooks for event-driven architectures
  • Implement polling with appropriate intervals for long-running operations
  • Consider using the async versions of API endpoints for resource-intensive operations

API Versioning

Novek.ai uses versioned APIs to ensure backward compatibility:

  • Major versions are indicated in the URL path (e.g., /api/v1/documents)
  • Minor updates are backward compatible and do not require URL changes
  • Deprecated endpoints are announced at least 6 months before removal
  • Multiple API versions are supported simultaneously during transition periods

Developer Resources

API Reference

Complete API reference documentation is available at: https://developer.novek.ai/api-reference

Interactive API Explorer

Test API endpoints directly from your browser: https://developer.novek.ai/api-explorer

Code Examples

Sample code for common integration scenarios: https://developer.novek.ai/examples

Developer Community

Connect with other developers integrating with Novek.ai: https://community.novek.ai/developers

Support

For developer support, contact: developer-support@novek.ai

Custom Development

For organizations with specific integration requirements, NovekAI offers custom development services:

Custom Connectors

Development of specialized connectors for proprietary systems or unique integration scenarios.

Extended API Capabilities

Custom API endpoints or enhanced functionality to support specific business requirements.

Embedded Solutions

Customized embedded components and white-labeled solutions for seamless integration with your applications.

Getting Started

1. Register for API Access

Sign up for API access through the NovekAI developer portal: https://developer.novek.ai/register

2. Create API Keys

Generate API keys through the administration portal with appropriate permissions for your integration.

3. Explore the API

Use the interactive API explorer to understand available endpoints and test requests.

4. Choose Integration Approach

Select the appropriate integration pattern and tools based on your requirements.

5. Implement and Test

Develop your integration using our SDKs or direct API calls, and test thoroughly in the sandbox environment.

6. Deploy to Production

Once testing is complete, deploy your integration to production using production API keys.

Conclusion

The NovekAI API provides powerful capabilities for integrating document intelligence into your applications and workflows. By following the guidelines in this document, you can create robust, secure, and efficient integrations that leverage the full potential of the platform.

For additional assistance or to discuss custom integration requirements, please contact our developer support team at developer-support@novek.ai.