GeotechOS
Reference

Build with an AI agent

Give an AI agent or a code generator the GeotechOS OpenAPI document and llms.txt, and the rules it must follow to write records safely.

An AI agent can read these docs and write an integration for you, or call the API itself. This page gives it the files it needs and the rules it must follow.

Files for agents and tools

File What it is
/docs/api/openapi.json The OpenAPI 3.1 document: every path, field, type and limit
/docs/api/llms.txt Every page of these docs as one Markdown text file

Most code generators and agent tools can read an OpenAPI document. Give the agent the address of the document, or download it and attach it.

A prompt to start with

Copy this prompt and change the parts in brackets:

Read https://www.geotechos.com/docs/api/llms.txt and
https://www.geotechos.com/docs/api/openapi.json.
Write a [Python] function that sends a new [booking from our website form]
to GeotechOS as a job on the project [ext id or number].
Use PUT with our own ids. Read the API key from the GEOTECHOS_API_KEY
environment variable. Handle 422, 409 and 429 as the docs say.

Rules for an agent

An agent that writes to GeotechOS must follow these rules:

  1. Keep the key secret. Read it from an environment variable or a secret store. Never print it, log it or put it in code or a web page.
  2. Check the key first. Call GET /whoami and read effective_abilities before writing.
  3. Use your own ids. Write with PUT /{resource}/ext:{id}. Then a retry cannot make a second record.
  4. Send the parents first. Client, then contacts, then project, then job.
  5. Never invent ids or emails. Use only ids from your own system, and only emails of real accounts. An unknown email is refused.
  6. Send times with an offset, for example 2026-11-03T07:00:00+11:00.
  7. Do not delete. Cancel a job, archive a project or make a client inactive.
  8. Stop on 409. A conflict needs a person. Report it, with the X-Request-Id.
  9. Wait on 429. Wait for the seconds in Retry-After.
  10. Ask before a large change. Show a person what the agent will send before it sends many records.

Test before you go live

Make a separate integration for the agent, with its own key. Its records then show the agent's provider slug, and you can disable its key at once in Settings › API keys.