Install Jentic One Beta
Jentic One is a self-hosted execution layer for AI agents. It lets your agent call the Ses Questionarios, or any other public or private API you need. You set the rules, the agent never sees your credentials, and every call is logged.
Two steps, two machines. Install the instance in a safe environment, then register your agent from wherever it runs.
Step 1: Jentic One Host machine
# On the machine that will host your Jentic One instance:
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Frota.sp.gov.br%2Frota-sp" | shStep 2: Agent machine
# On the machine where your agent runs (keep this separate from the instance):
curl -fsSL "https://jentic.com/install.sh?src=apis&api=%2Fapis%2Frota.sp.gov.br%2Frota-sp" | sh
jentic register # connects your agent to your Jentic One instanceJentic One is in public beta. The setup above keeps your agent separate from the instance, which is what you want before using real credentials: an agent running as the same OS user as Jentic One can read its stored keys directly. Just evaluating? A single local install is fine to start. See the secure deployment guide for the tiers.
What an agent can do with Ses Questionarios API.
Create or update a patient record keyed on the CPF in the federalId field, with address, phone, email, and birthDate
Record alcohol and nicotine dependency levels on a patient, such as HIGH_RISK, plus the cigaretteType used
Fetch a screening questionnaire by id with its questions and the answer options for each
Submit a completed questionnaire as idAnswer and idResponse pairs and read back the result and risk level
Patterns agents use Ses Questionarios API for, with concrete tasks.
GET STARTED
★ AI intake agent for SES health screening
An AI intake assistant for a São Paulo health service collects a patient's details and walks them through a screening questionnaire. Through Jentic the agent searches for 'register a patient by CPF', loads the criaPaciente operation with its input schema, and submits the record with an OAuth 2.0 token injected at call time. It then fetches the questionnaire, presents each question with its answer options, and posts the answers to get the scored result.
Call POST /paciente with federalId, patientName, birthDate, and address, then GET /questionario/1 and POST /questionario/resultado with the questionnaire id and the chosen idAnswer and idResponse pairs
Alcohol and tobacco dependency screening
A public health programme screens patients for alcohol and nicotine dependency and needs the risk band stored against each patient. The patient schema carries lifeWithoutAlcool and lifeWithoutNicotine objects with a dependencyLevel enum, such as LOW_RISK or HIGHEST_RISK, and a cigaretteType enum covering cigarettes, electronic cigarettes, hookah, and other forms. Submitting the questionnaire result returns a level string the programme can map to follow-up care.
Submit POST /questionario/resultado for questionnaire id 1 with the patient's answers, then call POST /paciente for the same federalId with lifeWithoutNicotine.dependencyLevel set to the band that matches the returned level
Rendering a questionnaire in a patient app
A patient-facing mobile or web app needs the current questionnaire content rather than hard-coded questions. GET /questionario/{id} returns the questionnaire name, description, and an answers array where each question carries its text and its list of response options with ids. The app renders the form from that payload, and a 204 response signals that no questionnaire was found for the id.
Call GET /questionario/1 and list each question text with its response options and their ids
3 endpoints — the ses questionarios api registers patients and runs health screening questionnaires for the são paulo state health secretariat (ses) integration platform.
METHOD
PATH
DESCRIPTION
/paciente
Create or update a patient by CPF
/questionario/{id}
Get a questionnaire with its questions
/questionario/resultado
Submit answers and get the risk result
/paciente
Create or update a patient by CPF
/questionario/{id}
Get a questionnaire with its questions
/questionario/resultado
Submit answers and get the risk result
What agents get from Jentic-routed access to this vendor.
Setup
Wiring the Ses Questionarios API by hand means registering an IdpSP client, running the OAuth 2.0 client credentials flow against the SP government Keycloak realm with the `api:integrador.ses-questionarios` scope, and refreshing tokens yourself. Through Jentic you install once, import the API from the API Directory, store the client credentials once, and your agent calls it.
Permission scoping
The three operations are distinct paths, and only the questionnaire read carries an id in the URL, so rules bound which operations your agent may call rather than which patient. You choose the operations it may call, so writes like patient creation or result submission are not included unless you add them.
Credential isolation
Your IdpSP client credentials are stored once, encrypted, by your own Jentic One instance and the token is injected at execution time. They never enter the agent's prompt, logs, or context.
Intent-based discovery
Agents search Jentic by intent such as 'register a patient by CPF' or 'submit questionnaire answers', and Jentic returns the matching Ses Questionarios operation with its input schema so the agent sends the right fields without reading the Portuguese reference.
Alternatives and complements available in the Jentic catalogue.
Specific to using Ses Questionarios API through Jentic.
What authentication does the Ses Questionarios API use?
Per its OpenAPI spec, the Ses Questionarios API uses OAuth 2.0 through the IdpSP identity provider, with client credentials and authorization code flows against the rhsso.idp-hml.sp.gov.br token endpoint. All three operations request the `api:integrador.ses-questionarios` scope. Through Jentic the client secret is held by your own Jentic One instance and the token is attached at call time.
Can I get a risk level from a completed questionnaire with the Ses Questionarios API?
Yes. POST /questionario/resultado takes the questionnaire id and an answers array of idAnswer and idResponse pairs, and returns a result string and a level such as Alto. Fetch the question and response ids first with GET /questionario/{id} so the submitted pairs match the questionnaire.
What are the rate limits for the Ses Questionarios API?
The OpenAPI spec does not specify rate limits. The spec was published on SwaggerHub under the ses-questionarios project, so check with the Rota SP integration team that issues your IdpSP client for any limits on the homologation and production gateways.
Is there a Ses Questionarios MCP server?
You do not need an MCP server to give your agent the Ses Questionarios API. Jentic connects it directly from the API Directory: import it, store your OAuth client credentials once, and your agent calls the patient and questionnaire operations on demand without extra tool definitions in its context.
How do I register a patient through Jentic?
Search Jentic for 'register a patient by CPF', load the POST /paciente operation, and execute it with federalId, patientName, birthDate, and the address object. The operation creates the patient, or updates the existing record when the CPF is already known. To run it on your own infrastructure, install Jentic One from its GitHub repo.
Can I limit what my agent is allowed to do with the Ses Questionarios API?
Yes. For a read-only assistant, write a rule that allows only GET /questionario/{id}, so the agent can show questionnaires to patients but cannot create patient records or submit results. Add the resultado operation when the agent should also score answers, and every call it makes is logged.
Know of an official OpenAPI document? Contribute it →
For Agents
Register or update a São Paulo SES patient by CPF, fetch a screening questionnaire, and submit answers to get a scored risk level.
Use for: Register a new patient in the São Paulo SES system using their CPF, Retrieve the screening questionnaire with id 1, Submit a patient's questionnaire answers and get the risk level, I want to update a patient's nicotine dependency level
Not supported: Does not book appointments, store clinical notes, or issue prescriptions. Use for SES patient registration and dependency screening questionnaires only.
The Ses Questionarios API registers patients and runs health screening questionnaires for the São Paulo state health secretariat (SES) integration platform. It creates or updates a patient record keyed on the patient's CPF (the federalId field), carrying address, contact details, and alcohol and nicotine dependency levels. A client fetches a questionnaire by id with its questions and answer options, then submits the chosen answers and receives a result with a risk level. The published server is the homologation (hml) environment of the Rota SP gateway.
This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use.
Base layer of spec validity and structural soundness.
Aggregated quality score from linter diagnostics, weighted by severity.
Percentage of `$ref` references that resolve successfully.
Checks whether the API description parses successfully and conforms to its declared specification (e.g., OpenAPI).
Structural correctness score based on schema issues using logarithmic dampening.
Clarity, completeness, and ingestion readiness for developers and tooling.
How richly the API is illustrated with examples.
Percentage of examples that conform to their schemas.
Percentage of operations with complete response definitions (success, client error, server error).
Health of API ingestion, bundling, and resolution within Jentic pipelines.
Semantic breadth, depth, and agent comprehension for AI systems.
Coverage of descriptions across API elements.
Coverage of RFC 9457 Problem Details for error responses.
Coverage, uniqueness, and casing consistency of operationIds for AI inference.
Coverage of summaries across operations/tags/info.
Functional utility, complexity comfort, and AI orchestration readiness.
Agent comfort level based on API operational and structural complexity.
Trust, risk posture, and security compliance.
Average quality of security schemes based on authentication method strength (weakest link for OAuth2).
Findability, semantic richness, and reasoning readiness.
Clarity and depth of descriptions across API elements.
Score it yourself
Every API in the directory is allowlisted, so you can re-score it with no key required.
npx @jentic/api-scorecard-cli score <openapi-url>