API integrations

An integration is a named API key that allows external software to access SynC on your behalf. Each integration has its own set of permissions — a subset of your own — so you can grant exactly the access each tool needs.

Common use cases include connecting AI agents (Claude, GPT, or custom LLMs), CLI scripts for bulk operations, BIM software for reading specifications, and procurement tools for accessing datasheets.

Integrations use the same API endpoints that the SynC web application uses. There is no separate "integration API" — any endpoint you can access in the browser, your integration can access via HTTP.

Navigate to your profile and select the Integrations tab. Click Create Integration to start.

You will be asked to provide:

• Name — A label for this integration (e.g., "My BIM Tool", "Procurement Bot", "Claude Agent").
• Description — Optional context about what the integration is for.
• Permissions — Select which actions the integration can perform. Templates are available as starting points.

After creating an integration, you receive an API key that starts with sync_. Use this key in the Authorization header of every HTTP request:

Authorization: Bearer sync_your_api_key_here

Example using curl:

curl -H "Authorization: Bearer sync_a1B2c3D4e5F6..." \
     https://your-sync-instance.com/api/projects

The API key acts as your identity. Every action taken with the key is attributed to your account, scoped to the permissions you selected. If your account permissions change (e.g., you lose access to a project), the integration's effective permissions update automatically.

For every endpoint — methods, paths, parameters, request body schemas, required permissions, and copy-pasteable curl examples — see the API Reference. It is generated from the live backend metadata, so it never drifts from the running API.

AI agents and other self-configuring clients can also call GET /api/help at runtime to retrieve the same catalog as machine-readable JSON.

The API returns standard HTTP status codes. Here are the ones most relevant to integrations:

Each integration has a per-minute request limit based on your subscription tier. Rate limit information is included in every response:

When the limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header indicating how many seconds to wait.

For AI agents: read X-RateLimit-Remaining after each response and slow down as it approaches zero. This prevents hitting the limit and keeps your integration running smoothly.

To connect an AI agent (Claude, GPT, or a custom LLM) to SynC:

1. Create an integration with Read-Only permissions (or broader if the agent needs write access).
2. Store the API key in your agent's environment (e.g., as an environment variable).
3. Configure the agent to include the Authorization: Bearer sync_... header on every request to your SynC instance.
4. Call GET /api/whoami to verify the key works and see what permissions and rate limits are available.
5. Call GET /api/help to get the endpoint catalog — a curated list of the resource APIs integrations drive (projects, standards, datasheets, files, libraries, categories, wiki), with the parameters and permissions each one needs.
6. Start making requests. GET /api/projects is the natural entry point to discover accessible data.

Tip for AI agents: Add ?format=compact to endpoints that support it (projects, standards, datasheets) to minimize response size and reduce token usage. The compact format strips metadata and returns only the most essential fields.

A typical AI agent workflow:

# 1. Verify connection and understand capabilities
GET /api/whoami
# Returns: { user: { name: "Jane Smith" }, permissions: [...], rateLimit: { ... } }

# 2. Discover available endpoints (optional — for self-configuring agents)
GET /api/help
# Returns: { endpoints: [{ method: "GET", path: "/api/projects", ... }] }

# 3. List projects
GET /api/projects
# Returns: { projects: [{ id: 1, name: "Hospital Phase 2", ... }] }

# 4. Get project details
GET /api/projects/details/1
# Returns: { id: 1, name: "Hospital Phase 2", vertical: "Healthcare", ... }

# 5. List standards in the project
GET /api/standards?project_id=1
# Returns: { standards: [{ id: 42, name: "Panelboards", ... }] }

# 6. Read standard content
GET /api/standards/42
# Returns: { standard: { id: 42, elements: [...], ... } }

• Least privilege. Only grant the permissions each integration actually needs. A reporting tool does not need write access.
• One integration per tool. Create separate integrations for separate tools. If one is compromised, you can revoke it without affecting the others.
• Rotate periodically. Rotate your API key on a regular schedule, even if you don't suspect compromise.
• Revoke immediately if compromised. If a key is leaked (e.g., committed to a public repository), revoke it from your profile immediately. Revocation is instant — the old key stops working with no grace period.
• Store keys securely. Use environment variables or a secrets manager. Never hardcode keys in source code.
• Choose professional names. Integration names appear in audit logs, revision histories, and may be visible to other users on shared projects. Use descriptive, professional names.

From the Integrations tab in your profile, you can:

• View your key — requires entering your password for security.
• Rotate your key — generates a new key and instantly invalidates the old one.
• Edit permissions — add or remove permissions from an existing integration.
• Revoke — permanently disable an integration. This cannot be undone.