Use your API key

This page is for whoever sets up the tool: you, a developer, or someone at the company that makes the tool.

Send the key with every call

sherlock’s API is at https://api.gosherlock.ai/api/v1. Put your key in the Authorization header of every call, after the word Bearer:

curl https://api.gosherlock.ai/api/v1/companies/YOUR_COMPANY_ID/orders \
  -H "Authorization: Bearer sk_live_your_key"

Replace YOUR_COMPANY_ID with your company’s ID, and sk_live_your_key with your key. If you don’t know your company ID, ask your sherlock contact.

A call that works answers with "success": true and the data:

{ "success": true, "data": { "results": [ ... ] } }

Some calls you can make

What	Call	Permission it needs
List your orders	GET /companies/YOUR_COMPANY_ID/orders	Read orders
Search your orders	GET /companies/YOUR_COMPANY_ID/orders/search	Read orders
List your inspections	GET /companies/YOUR_COMPANY_ID/inspection-requests	Read inspections
List your products	GET /companies/YOUR_COMPANY_ID/products	Read products
List your agreement templates	GET /companies/YOUR_COMPANY_ID/agreement-templates	Read agreement templates

When sherlock says no

A refused call answers with "success": false and a reason that says why:

{
  "success": false,
  "error": { "reason": "API_KEY_INVALID", "code": "UNAUTHORIZED", "message": "Invalid API key" }
}

Status	reason	What it means	What to do
401	API_KEY_INVALID	The key is wrong, or it was revoked	Check the key was copied whole. If it was revoked, create a new one
403	FORBIDDEN	The key doesn’t have the permission this call needs	Create a key with that permission
403	WRONG_COMPANY	The address names a company that isn’t yours	Use your own company ID
404	ends in _NOT_FOUND, like ORDER_NOT_FOUND	The thing asked for doesn’t exist in your company	Check the ID in the address
429	API_KEY_RATE_LIMITED	The key made more than 60 calls this minute	Wait a minute, then try again. Space calls out

Keep your key safe

• Treat the key like a password. Anyone who has it can do what it allows.
• Keep it in your tool’s settings or a password manager, never in an email, a chat or a shared document.
• Give each tool its own key, so you can revoke one without breaking the others.
• If a key may have leaked, revoke it right away and create a new one.