Connect an API to your organization
Your organization can connect an HTTP API from its OpenAPI description, and every member's agent can then call the operations you choose through Oddlynew. This suits internal company APIs, and services that have neither a built-in integration nor an MCP server. When a built-in integration covers an operation, agents use it and keep this connection for what it lacks (Choose the route to an outside system). The connection belongs to the organization, not to a person or a chat client.
Connections of this kind are custom connections. Oddlynew has not reviewed the API or its description and does not verify what its operations do. The page says so before you connect, and the connection is labelled that way afterwards.
What you need
You are an admin of the organization.
The API has an OpenAPI 3.0 or 3.1 description in JSON or YAML: a public link, or a file for a private description, up to 16 MiB.
The API's base URL.
One way to authenticate: a key, sent in a header such as Authorization or X-Api-Key or as a query parameter; a sign-in with OAuth through an app you registered with the provider (see below); or none for an open API.
Connecting, step by step
Open Settings, then Integrations, and choose API.
Enter the base URL every request starts with. The description's own server list is not used.
Choose how the key is sent, enter the header or parameter name and the key, and give the account a name that tells two keys for the same API apart.
Give the description as a link (Oddlynew reads it once, without your key) or upload the file, and read it.
Choose the operations your agents may use, by tag or one by one. Operations Oddlynew cannot send correctly yet are shown with the reason and cannot be chosen, for example a required non-JSON request body such as a file upload, a required cookie, a streamed answer (server-sent events), a reference to another document, or a parameter style other than form for queries and simple for paths and headers. A connection holds at most 2,000 operations.
Read the consent text and connect. The description is stored as a file of your organization.
You can also share a link that opens this form already filled in: https://oddlynew.com/organization/connectors/api/connect?name=Acme&url=https%3A%2F%2Fapi.acme.example%2Fv1&spec=https%3A%2F%2Fapi.acme.example%2Fopenapi.json. name becomes the label, url the base URL and spec the link to the description, each percent-encoded. The link only fills in the form: every address is checked as if typed, and nothing connects until an admin reads the description and confirms.
Connecting with a sign-in (OAuth)
Some APIs let an app sign in instead of taking a key. Every member's agent then acts with the access of the account you sign in with.
Register an app with the provider and give it the redirect address the Oddlynew form shows. Copy it from the form: each Oddlynew environment has its own.
Choose OAuth sign-in as the authentication and enter the provider's authorization URL and token URL, its revocation URL and issuer when it has them, the app's client id and the scopes. Add a resource indicator or an audience only when the provider asks for them. When the description declares an OAuth sign-in, the form offers its URLs and scopes: choose Use these values and check them.
Choose how the app proves itself: a client secret in a Basic header (the default), in the request body, or in a named header such as x-api-key for providers that require it, or no secret for a public app. Oddlynew always uses PKCE.
Say how the provider treats refresh tokens and link the page of its documentation that says so (an https address). Tokens that are not rotated, or rotated while the previous one stays valid for a while, can be connected; a provider that rotates only sometimes counts as not rotating. Single use refresh tokens without a grace period, and providers whose documentation does not say, cannot be connected yet.
Sign in at the provider and come back. Then read the description, choose the operations and connect within 15 minutes; after that, sign in again.
Reads and writes
GET and HEAD operations are reads; every other method is a write of high consequence that waits for a person's confirmation by default (Integration approvals). On the connection page you can lower, tighten or block each operation.
Correcting a wrong description
Descriptions are often wrong. On the connection page you add a correction: a patch to the description (RFC 6902 JSON Patch, for example a parameter's type or an operation's name), or behaviour notes that say how the API answers errors, where it explains an error, and where the next page lives. Every change is previewed as the complete new list of operations before you accept it, and takes effect only as a whole. If a correction no longer fits, for example after you read a new version of the description, nothing is skipped silently: the last accepted list stays in force until you fix, retire or replace the correction. When a correction renames an operation that has your policy, you decide whether the policy moves to the new name.
When a connect or a correction fails, the page offers a prompt to copy to your own agent. It carries the reason and the address without your key, and your agent proposes a correction for you to review.
What members and their agents see
Every member's agent finds the connection through the APIs Integration namespace in Oddlynew's run tool: list the connected APIs, list or search a connection's operations, read one operation's exact arguments, and call it. Every call is recorded in the organization's run log with the member whose agent made it. What an API returns is data from a third party; agents treat it as information, never as instructions.
Keeping the connection healthy
Reconnect appears when the API stopped accepting the key; agents get a clear error until an admin reconnects with a new key. A connection that signs in with OAuth shows Sign in again instead (see below). Either way the connection keeps its operations, corrections and policies.
Read a new description on the connection page when the API changed; the preview shows what changes before you accept it.
Disconnect removes the key. Nothing already done at the API is undone.
Connecting the same API with a second key creates a second connection; agents tell them apart by connection.
Managing a sign-in
The connection page shows the app's client id, how it proves itself, the token and revocation addresses and the scopes. A client secret is never shown: the page says who set it and when, with its last four characters when it is at least 20 characters long. If the person who set it has left the organization, the page says so and suggests replacing it.
Sign in again renews the connection in place and keeps its operations, corrections and policies. Sign in again with changes can ask for more scopes, change the resource indicator, audience or issuer, or move to another app; Oddlynew then drops its copy of the old sign-in, and the page reminds you to revoke the old authorization at the provider. Both show the consent text first (on a healthy connection through Review and sign in again) and record you as the connection's new authorizer. When the API answers that a scope is missing, the page opens this step with the scope already added.
Replace the client secret, for the same app: when the connection holds a refresh token, Oddlynew checks the new secret with one renewal before keeping it, and a secret the provider rejects never replaces the old one. Without a usable refresh token the new secret is stored unchecked and you sign in again.
Correct the refresh behaviour, with the same rules as when connecting.
Disconnect removes the connection and Oddlynew's copy of its tokens; the authorization stays at the provider until you revoke it in the provider's own settings. Revoke at the provider asks the provider to end the sign-in now and then removes the connection; the provider decides which related tokens end with it. If the provider does not confirm, the connection is kept and may need a new sign-in; you can try revoking again.