OiAir API · OiAir

Overview

Public queries do not require an API key. They return published organization and group information without parents’ or children’s personal data.

This documentation covers catalog reads. Organization management, enrollment lists and request decisions require authorization and are outside this public API.

First query

Search for an activity and limit the response. Use the returned IDs to read an organization or a specific publication.

Search drawing for age 6

curl --get 'https://oiair.com.br/api/v1/search' \
  --data-urlencode 'q=desenho' \
  --data-urlencode 'age=6' \
  --data-urlencode 'city=Florianópolis' \
  --data-urlencode 'limit=5' \
  --data-urlencode 'locale=en'

Open the OpenAPI contract

The contract describes this integration’s public endpoints. Use the fields and response codes it defines.

Endpoints

Method	Path	Returns
GET	`/api/v1/search`	Ordered search with filters and pagination.
GET	`/api/v1/catalog`	Public organization catalog.
GET	`/api/v1/organizations/{organizationId}`	An organization’s public profile and published groups.
GET	`/api/v1/offerings`	Current publications; accepts organizationId, age, city, text and after.
GET	`/api/v1/offerings/{publicationId}`	A current publication identified by publicationId.
GET	`/api/v1/openapi.json`	OpenAPI contract for public reads.

Search and filters

Age, days and time in a search must match the same published group. Days use numbers from 0 (Sunday) to 6 (Saturday); multiple days mean “any of”.

Parameter	Usage
`q`	Free text: activity, group name or organization.
`age`	Age from 0 to 18, within the group’s inclusive age range.
`city / neighborhood`	The location’s city and neighborhood.
`days`	Comma-separated days, such as 2,4.
`period`	manha (morning), tarde (afternoon) or noite (evening).
`after17`	true for times from 17:00 onward.
`locale`	pt-BR, ru, en or es for interface text.
`limit / cursor`	Up to 50 results; reuse the cursor with the same filters.

Using the data

Keep organizationId, publicationId and version. Do not silently replace a changed or withdrawn group with another one.
Show the location and the selected group’s conditions. Do not reuse a price or schedule from another address.
Respect freshness.checkedAt and freshness.validUntil on publications. Read the publication again before directing the family to the form.
A published group and a form link do not confirm availability. The organization must confirm the request.
Search returns a ranked shortlist, not the whole catalog. Preserve unresolvedConstraints and resultScope; follow nextCursor when present. Do not claim an exhaustive count.

The OiAir form sends a request to the organization. Submitting it does not reserve a place. This read connection does not submit requests or confirm enrollment.

Responses and errors

Handle unavailable data explicitly. Do not fill in unknown conditions or reuse a withdrawn group.

HTTP	Usage
`400`	Invalid parameter or filter: correct the query.
`404`	Organization or publication unavailable: search again.
`409`	Catalog or version changed: discard the old cursor and query again.
`410`	Cursor expired: restart the search.
`503`	Search or catalog temporarily unavailable: try again later.

Integration and releases

See connection examples and release history on GitHub. Read the server metadata in the MCP Registry.

Examples and releases on GitHub MCP Registry metadata

Next step

Building an agent? Use the MCP server to access the same data through tools.

MCP server