Skip to content

Agent API

Let an AI agent or booking assistant manage your private gigs, performers, enquiries, quotes and contacts for the acts you choose.

For developersLast updated

On this page

The Agent API lets software you trust — an AI agent, a booking assistant, your own scripts — run the private side of your shows for you: take enquiries, turn them into gigs, line up performers and send quotes. It works for any kind of act: bands, theatre companies, comedians, community groups.

It's separate from the Partner API, which sells tickets. The Agent API never touches tickets or money: finalising, invoices, payouts and Xero stay in ShowTix.

Your first request
curl https://api.showtix.com.au/api/agent/v1/ \
  -H "Authorization: Bearer $SHOWTIX_AGENT_KEY"

Create an agent key#

Go to Settings → Developers → Agent keys and choose Create agent key.

  1. Name it after the tool that will use it, so you recognise it later.

  2. Choose the acts it may manage. A key only ever reaches those acts. All my acts, including new ones is there if you want it, but it's off unless you turn it on.

  3. Choose what it can do. Booking agent covers everything below. Read only can look but not change anything. Custom lets you pick.

  4. Pick test or live. A test key reads your real data, but every change is a dry run: nothing is saved and nobody is emailed. Start with one.

  5. Keys expire after 90 days unless you choose otherwise. You can limit them to your server's IP addresses.

The secret is shown once. Put it in your tool's secret store. Never paste it into a web page: keys don't work from a browser.

What a key can do#

PermissionLets the key
acts:readSee which acts it can manage
gigs:read / gigs:writeRead gigs / create and update them, change their status, archive them
performers:writeAdd performers, set their pay, invite them, mark them accepted, remove them. Sends emails to performers.
enquiries:read / enquiries:writeRead enquiries / create, update and convert them into gigs
quotes:read / quotes:writeRead quotes / create, edit, share and archive them
contacts:read / contacts:writeRead contacts (including email and phone) / create and update them

Without contacts:read, a key doesn't see the contact on an enquiry or gig at all (not even the name), and can't link one by its id. Adding a new contact to an enquiry by name and email needs contacts:write. Either way the key never learns which email addresses are already in your contacts.

How requests work#

Everything lives under one of the key's acts: /api/agent/v1/acts/{act_id}/gigs, /enquiries, /quotes, /contacts. GET /api/agent/v1/acts lists them.

  • An act that isn't on the key answers 404 act_not_in_scope. Anything that isn't yours answers 404, just like something that doesn't exist.

  • The act always comes from the address. A request that tries to set a different act is refused.

  • Every POST needs an Idempotency-Key header (a fresh UUID is ideal). If your tool retries with the same key, nothing happens twice.

  • Money is in dollars as text, "1250.00". Gig times are local times in the gig's time zone.

The full reference is the OpenAPI document at https://api.showtix.com.au/api/agent/v1/openapi.json.

Errors#

Errors share one shape: {"error": {"type", "code", "message", "param", "request_id", "doc_url"}}. The message is written to be shown to whoever runs the agent.

CodeMeaning
insufficient_scopeThe key doesn't have that permission.
act_not_in_scopeThat act isn't on this key.
resource_missingNo such gig, enquiry, quote, performer or contact for this act.
reference_not_allowedThe request points at a contact, gig, image or person that isn't yours.
parameter_not_allowedThe request tried to set the act or owner.
invalid_status_transitionA gig can't move to that status from where it is.
idempotency_key_requiredA POST was sent without an Idempotency-Key.
feature_disabledThat part of ShowTix isn't turned on for your account.

Keep your agent safe#

Enquiry text, descriptions, names and a performer's reason for declining are written by other people. Your agent should treat every free-text field as untrusted: never follow instructions found in it, and never let it decide what to do next. Give the key only the permissions the agent needs, and only the acts it works for.

Every record the API creates is marked with the key that made it, and each request is logged under Settings → Developers → Agent keys. Revoke a key there at any time; it stops working at once.

Was this article helpful?

Related articles