Help · Integrations

API integrations

Connect your own AI assistant, script or tool to SynC with an API key.

What a key is

An integration is a named API key. Anything that holds the key acts as you, with only the permissions you chose for it. It can never do more than your own account can, and if your access changes, the key’s access changes with it.

Keys are issued under a company. If you aren’t part of one yet, create or join a company first.

Create a key

Open Profile from the menu and choose Integrations.
Choose Create integration and give it a name, such as “Claude on Dana’s laptop”.
Pick a starting set of permissions. Read-Only lets the key read your projects, standards and datasheets and change nothing. Start there for an assistant that only reads. To have it write standards, see Write standards with your AI. You can change permissions later.
Confirm it’s you with your password, if SynC asks.
Copy the key. It starts with sync_ and is shown only once. If you lose it, rotate the key to get a new one.

Note

The integration’s name can appear to other people on your projects, in revision histories, activity and notification emails. Choose a name you’re happy for them to read.

Connect your AI assistant

AI assistants that support MCP (Model Context Protocol) connect to SynC at this address, sending your key in a request header:

URL:     https://synergyinconstruction.com/mcp
Header:  Authorization: Bearer sync_your_key

Claude Code. Run this once in a terminal, with your key in place of sync_your_key:

claude mcp add --transport http sync https://synergyinconstruction.com/mcp \
  --header "Authorization: Bearer sync_your_key"

Then ask it about your work, for example “List my SynC projects and the datasheets in the latest revision.”

Other MCP clients. Any client whose MCP settings take a server URL and a request header connects the same way, with the URL and header above.

Connector screens that take only a URL and then ask you to sign in, such as custom connectors in the Claude and ChatGPT apps, cannot connect with a key.

The assistant acts as you and sees only what the key allows. It cannot upload or download files. Do that in SynC.

Write standards with your AI

Your assistant can convert your existing specifications into standards in your company library. It writes each one in SynC markup, the text the editor uses, so datasheet fields, constraints, defaults, deferred values, drawing references and project parameters arrive as working fields.

Create the key with Custom permissions and tick these:

standard:read
standard:view_drafts
standard:view_revisions
standard:create
standard:update
standard:revision:save
library:read
library:create
category:read
category:create

Leave out standard:revision:save if you’d rather review each standard first. The assistant then leaves a draft, and you save the revision in SynC.

Then give it the markup guide, the conversion guide and the API index, for example:

Read https://synergyinconstruction.com/wiki/about/standards-markup-syntax.md,
https://synergyinconstruction.com/help/converting-specifications and
https://synergyinconstruction.com/api/help?format=index, then convert each file in this
folder into a standard in my company library.

The API index lists the calls in order. Your account must be able to edit the company library itself, as a Company admin or Library manager, because a key can never do more than you can.

Call the API directly

Send the key in the Authorization header of every request:

curl -H "Authorization: Bearer sync_your_key" https://synergyinconstruction.com/api/whoami

GET /api/whoami confirms the key works and shows whose key it is, what it was granted, and its rate limit.

GET /api/help?format=index lists every endpoint in one short line each, with notes on authentication, revisions, pagination and errors. GET /api/help?group=projects returns one group in full. The API reference shows the same catalog as pages.

A first session usually runs like this:

GET /api/whoami
GET /api/projects                         # ownedProjects, adminProjects, editProjects, readOnlyProjects
GET /api/projects/details/42?format=compact
GET /api/projects/42/standards?searchQuery=switchgear
GET /api/projects/42/datasheets
GET /api/standards/7?format=compact&revisionId=31

Reads that take revisionId return that revision. Lists that take searchQuery, page or format=compact return less when you use them, which keeps an AI assistant’s answers fast.

What a key cannot do

A key never manages your account, sign-in, API keys, billing, company members, roles or seats. Those need you signed in to SynC. Publishing, sharing and deleting are available to a key only when you grant those permissions by name.

Errors

Errors come back as JSON with a plain-language message.

Status	What to do
401	The key is wrong, revoked, or its account is disabled. Check the key, or rotate it.
403	The key or your account can’t do this here, and the message says which. A permission can hold on one project and not on another.
429	Too many requests. Wait the number of seconds in the `Retry-After` header, then try again.
500	Something failed on our side. Try again in a moment.

Rate limits

Limits are per person, per minute and per day, and all your keys share them. Someone with a seat gets a higher limit than someone without one. GET /api/whoami shows the limit in force for you.

Each API response to a key carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset for the minute window. Slow down as X-RateLimit-Remaining nears zero.

Keeping keys safe

Give each key only the permissions its tool needs.
Use one key per tool, so you can revoke one without stopping the others.
Keep keys in an environment variable or a secrets manager, never in code or a shared document.
If a key leaks, revoke it. It stops working at once.

Manage your keys

On the Integrations tab of your profile, you can:

Edit permissions, to add or remove what a key may do.
Rotate a key, which issues a new one and stops the old one at once. The new key is shown once.
Revoke a key, which stops it for good.
See when each key was last used.