Creating your own client

The agent server publishes an OpenAPI schema, so a client in any language can be generated with standard tools.

Generating a client

$ curl http://127.0.0.1:9020/openapi.json > openapi.json
$ npx orval --input openapi.json --output ./search2o-client   # TypeScript
$ openapi-generator-cli generate -i openapi.json -g python     # Python, Java, Go, ...

The schema carries every request and response model, including the streamed line types of execAgent, so a generated client knows the shapes without hand-written definitions.

A client in a browser

A browser client that is not served by the agent server runs on a different origin. The agent server allows every origin by default. If an administrator has narrowed the allowed CORS origins in the Agent servers configuration, add yours, or the browser will refuse the calls. Use the session cookie rather than a bearer token: the cookie is HTTP-only and never visible to page scripts.

Rules a client must follow

• Send only the fields an endpoint declares. An unknown field is rejected with status 422.
• Check success in every response, and show error.message to the user when it is false; the message is written for that purpose.
• Sign in again when a response has status 401, then repeat the call.
• Keep the convid from an execAgent response if the user may follow up.
• Read a streamed response line by line rather than waiting for the whole body.