Documentation

API Reference

Build custom integrations with the AVStackr REST API to sync products, automate project creation, and connect with your existing tools.

Base URL

https://avstackr.com/api/v1

Authentication

All API endpoints require authentication using a JWT (JSON Web Token) Bearer token. Include the token in the Authorization header of every request:

Authorization: Bearer YOUR_JWT_TOKEN

To obtain tokens, call the login endpoint with your email and password. Access tokens expire after 15 minutes. Use the refresh token to obtain new tokens without re-authenticating.

Available Resources

Resource Base Path Description
Authentication /api/v1/auth Login, view profile, refresh tokens
Products /api/v1/products Create, read, update, delete products in your catalog
Customers /api/v1/customers Manage customer records with billing and shipping addresses
Projects /api/v1/projects Manage projects, rooms, equipment, and generate reports
Vendors /api/v1/vendors Manage vendor/distributor entity records
Vendor Config /api/v1/vendor-config Configure vendor API credentials and test connections
Global Config /api/v1/global-config Default project settings for your organization
Bundles /api/v1/bundles Reusable equipment packages for quick room setup
Proposal Templates /api/v1/proposal-templates Create and manage templates for proposal generation
AI Features /api/v1/ai Semantic search, embeddings, and AI-powered suggestions
Knowledge Base /api/v1/knowledge-base Search manufacturer technical documentation (Biamp, Crestron, and more)
Invoices /api/v1/invoices Save and retrieve generated invoices
Schematics /api/v1/schematics Signal flow diagrams with AI auto-wiring
Room Drawings /api/v1/drawings Floor plans and elevations for project rooms

Response Format

All API responses use a consistent JSON envelope format:

{
    "success": true,
    "data": { ... },
    "timestamp": "2024-12-25T12:00:00Z"
}
Field Type Description
success boolean Indicates whether the request was successful
data object Response payload (varies by endpoint)
timestamp string ISO 8601 formatted UTC timestamp
error object Error details (only present when success is false)

Pagination

Endpoints that return collections support pagination using page and pageSize query parameters:

GET /api/v1/products?page=1&pageSize=20

Paginated responses include a pagination object with navigation metadata:

{
    "pagination": {
        "currentPage": 1,
        "pageSize": 20,
        "totalCount": 150,
        "totalPages": 8,
        "hasPrevious": false,
        "hasNext": true
    }
}

Versioning

The API uses URL-based versioning. The current version is v1. We maintain backwards compatibility within a version and will provide migration guides when new versions are released.

Rate Limiting

The API does not currently enforce rate limits. However, we recommend implementing reasonable request throttling in your integrations. Excessive usage may result in temporary blocks.

Data Isolation

All API requests are scoped to your organization (tenant). You can only access data belonging to your organization.

Common Workflows

These examples show how to combine API endpoints for typical automation scenarios.

Create a Project with Equipment

Build a complete project from scratch with rooms and equipment:

  1. POST /api/v1/projects - Create the project with basic info and rates
  2. POST /api/v1/projects/{id}/rooms - Add rooms to the project
  3. POST /api/v1/projects/{id}/rooms/{roomId}/items - Add equipment to each room
  4. GET /api/v1/projects/{id}/reports/financial-summary - Get calculated pricing

Generate a Proposal

Create a professional proposal document from project data:

  1. GET /api/v1/proposal-templates - List available templates
  2. GET /api/v1/proposal-templates/variables - See all 70+ available variables
  3. POST /api/v1/proposal-templates/{id}/generate - Generate with project data
Designer templates

Templates built with the drag-and-drop block builder return a complete, themed HTML document (cover page and all). Classic HTML templates return the body only. Append ?format=body to generate or preview when you want just the bare content from a builder template.

AI-Powered Product Search

Use semantic search to find products by natural language description:

  1. GET /api/v1/ai/embeddings/status - Check if embeddings exist
  2. POST /api/v1/ai/embeddings/generate - Generate embeddings if needed (run multiple times for large catalogs)
  3. POST /api/v1/ai/semantic-search - Search using natural language queries

Create Signal Flow Schematics

Initialize a project's schematics, then save the layout as devices are placed and wired:

  1. POST /api/v1/projects/{id}/schematics - Initialize schematics for the project
  2. PUT /api/v1/schematics/{id} - Save the updated layout (layoutJson)
  3. GET /api/v1/schematics/{id}/export/dxf - Export to CAD format

Quick Room Setup with Bundles

Apply pre-configured equipment packages to project rooms:

  1. GET /api/v1/bundles - List available bundles
  2. GET /api/v1/bundles/{id} - View bundle contents
  3. POST /api/v1/bundles/{id}/apply - Apply bundle to a project room

Generate and Save Invoices

Create invoices and store them for future reference:

  1. POST /api/v1/projects/{id}/invoice - Generate invoice HTML
  2. POST /api/v1/projects/{id}/invoices - Save the invoice configuration
  3. GET /api/v1/invoices/{invoiceId} - Retrieve saved invoice (regenerates with current data)