Organizations

What it does

The organizations namespace is where agent work in Oddlynew begins. Organizations are the knowledge and access boundary: documents, files, integrations, and permissions all belong to one, and almost every other namespace takes an organizationId that comes from here. This namespace discovers those organizations, explains what you are allowed to do inside one, creates new ones, administers who belongs to them, reports which citations have gone stale, and drives the reversible deletion lifecycle. Authorization is checked live at every call, so an organization created earlier in the same script is usable by the next line.

Start here: listMine returns an envelope

organizations.listMine returns an object, not an array. Its shape is { organizations, hasMore, nextCursor? }, and the organization rows live under organizations. Calling .map on the result itself is the single most common way to crash a first script, and it fails with a type error that looks nothing like the real cause. Keep the envelope in a variable and read page.organizations from it; do not destructure it into a name that shadows the organizations namespace itself.

Only memberships that are currently active and unexpired produce a row, so an organization missing from the list is usually an expired or pending membership rather than a bug. Rows are ordered by organizationId and paged by a cursor that is itself an organization id; the default page is 20 rows and the maximum is 100. Pass query for a case-insensitive contains search on the name. Every row also carries a lifecycleStatus, which is active for a normal organization and one of deleting, quarantining, quarantined, tearing_down, or deleted for one that is being wound down. A non-active organization will refuse ordinary work, so check this before planning a long sequence of writes against it.

The example shows the flow; live server validation inside run is authoritative for exact parameters.

AGENTS.md is the deterministic guidance entrypoint

Each listMine row carries an agentsMd field, and it exists so that finding an organization's operating instructions never requires a search. It is a tagged union with four states. available carries the exact documentId of the single active AGENTS.md, and you should read that document before doing substantive work in the organization. not_configured means the organization has none, and its recommendedAction suggests considering one. ambiguous means more than one document claims the role, and the field deliberately refuses to choose between competing guidance: consolidate them rather than picking one. unavailable means your principal lacks document-read permission there, and it is careful to reveal nothing about whether guidance exists.

Read the status field and branch on it. Do not treat a missing documentId as "no guidance", because three of the four states have no documentId for three different reasons, and only one of them means the organization actually lacks an AGENTS.md.

Why a call was denied: getMyAccess

When a call fails with a permission error, organizations.getMyAccess is the diagnostic. It answers for exactly one organization and returns four things: roles, your live role keys there; enabledFeatures, the features that organization has switched on; organizationPermissions, the permission strings those two produce together; and delegatedScopes, the OAuth scopes your token actually carries.

The reason it takes four fields to answer one question is that two independent planes constrain every call. Your token's scopes are one plane: without mcp:write no mutation succeeds, regardless of how senior your role is. The organization's permissions are the other: a permission exists only where a role grants it and the organization has the owning feature enabled, so an administrator in an organization with document management switched off genuinely cannot read the reference ledger. A denial means one plane refused, and comparing the two lists tells you which, and therefore whether the fix is reconnecting with a broader token or asking an administrator for a role.

The example shows the flow; live server validation inside run is authoritative for exact parameters.

Creating and shaping an organization

The method to create one is organizations.createOrganization. It is not organizations.create, and guessing the shorter name is a common first failure. It takes a name, makes you its administrator, and returns an organizationId that authorizes immediately: later calls in the same run script can use it, and no reconnection is required.

API-key principals cannot create organizations at all. A key's entire authority is the set of organizations it was provisioned into, so allowing it to found one it would then administer would let a narrow key widen itself. Creation is available only over a delegated OAuth connection, or to a person in the web app. If you are running as a key and need a new organization, that is a request to hand back to a human rather than a call to retry.

Once created, renameOrganization changes the display name and nothing else, and it rejects a name with surrounding whitespace rather than trimming it, so send exactly what should be stored. setOrganizationVisibility flips the organization between private and public with an explicit target, which makes retries idempotent. It is the one method whose organizationId may be omitted, and omitting it means your current default organization; when you have no default, the call fails and tells you to pass one explicitly, so prefer being explicit. A public-to-private flip returns a count of inbound cross-organization citations, masked to the source organizations you are entitled to see, which is your signal for how much other people's work is about to lose its reference.

Administering membership

listMembers returns active members and pending invitations together, in an envelope of { organizationId, lifecycleStatus, members, hasMore, nextCursor? }. Each row's status is the field that decides which removal method applies: invited and provisioned rows are revoked with revokeInvitation, and active rows are removed with removeMember. Using the wrong one fails rather than doing the other thing. Rosters carry email addresses and phone numbers, so the method requires the same permission the product's team page enforces rather than bare membership.

inviteMember creates the invitation and, unless you pass notify: false, sends the email. In every case it returns a single-use inviteUrl. Treat that URL as a credential: anyone holding it can accept the membership, so it does not belong in a document, a log line, or a summary you hand back to a wide audience. Note that expiresAt on the input is when the granted membership access expires, which is a different thing from the invite link's own thirty day lifetime.

Two failure modes deserve care. If email delivery is refused, the invitation is rolled back automatically, and the error says whether that rollback actually completed; when it did not, inspect listMembers before inviting again so you do not create a duplicate. If the delivery outcome is unknown, nothing is rolled back and the invitation stays pending: do not retry automatically, because the email may well have been sent. Separately, an organization may create at most 50 invitations per UTC day, and re-inviting the same person inside a 30 second cooldown is refused; both are shared with the web app, so an agent and a person working the same organization draw on one budget.

Removals have their own guard: the last non-expiring active administrator cannot be removed, and the attempt comes back as a membership-state conflict telling you to refresh and reconsider. Removing an active member also flips the organization connectors that person authorized to needs_reauth, which is honest rather than broken: the organization sees a remediable status immediately instead of a connector that silently stops working.

The example shows the flow; live server validation inside run is authoritative for exact parameters.

Connections, API keys and capacity

Connections. listConnections({ organizationId }) lists the organization's shared connections (Google, Meta, MCP servers, APIs and other connected services), each with the run namespace that calls it and its connectorId, which you pass to that namespace as sourceId. Call it before you reach for a provider key, a shell or another connector. Each row says whether the connection is active or needs_reauth, whether it is paused or needs a scope upgrade, its confirmation policy and who authorized it, and carries pageUrl, the web page where a person reconnects or manages it. Connecting and reconnecting need a person's consent in the browser, so when a connection needs attention, hand pageUrl to an organization administrator. It needs mcp:read and the permission to use the organization's connections.

An Admin's agent can also change a connection. renameConnection changes only its display label. setConnectionNote sets or clears a note that everyone who sees the connection reads; it stays when the connection is reconnected. pauseConnection stops everyone, agents included, from using the connection until a person resumes it on its web page; the provider authorization stays, so resuming needs no new sign-in. Resuming and disconnecting are done on the web page only.

API keys. listApiKeys({ organizationId }) lists the organization's keys that are not revoked, with metadata only: name, label, kind (a shared agent's key or a Content API site key), display prefix, roles, and when it was created, expires and was last used. Expired keys are listed too, so compare expiresAt with the current time; a null expiresAt never expires. No secret is ever returned, and keys are created by a person on the web page, never here. revokeApiKey revokes one at once and cannot be undone; the public API may still accept the key for up to about 75 seconds. A member's personal key is never in scope. Both need an organization administrator with permission to manage keys; revoking also needs mcp:write.

Capacity. getCapacity({ organizationId }) reads what the organization's billing page shows: its plan, the documents it holds against its limit, and how much input, read and search capacity is left and when it refills. Call it before bulk work instead of learning the limit from a refusal. It is read-only, never returns payment details, and answers organization administrators only.

Citation health: referenceAttention and listReferenceFindings

Documents in Oddlynew cite each other, and citations go stale. Each listMine row carries a referenceAttention summary, and listReferenceFindings turns those counts into the documents involved.

The summary's most important property is that zero never means healthy. Read structuralCoverage first: unknown means nothing has been verified for that organization yet, partial means at least one cited document is still awaiting verification, and only complete means every cited document carried a full proof when the row was built. Alongside it, pendingTargets and oldestPendingAt say how much verification is still owed, counting both cited documents awaiting a scan and your own changed documents the verifier has not reached. A row of zeros under unknown coverage says nothing has been checked, not that everything is fine. The whole field is null when nothing has been verified yet, and also when you lack org:document_management:read there, which are two very different situations that look identical from outside. Comment threads never enter these counts: a comment anchors the passage it discusses, and that anchor drifting is the comment's own lifecycle.

listReferenceFindings takes a required bucket. confirmed means the citation no longer resolves, because the cited block, the pinned version, or the whole cited document is gone. review means the cited block still resolves but its content changed, so a person or agent has to judge whether the citation still holds. Findings are paged by citing document, and each finding lists targets with the exact basis they were proved at and occurrences giving the block key, mark key, anchor text, and what the citation pins. That is enough to open the passage and compare it against the cited block as it is now.

Repair differs by bucket. A review citation that still holds is re-cited by rewriting its block unchanged: the citation re-pins to the current content and the finding clears on the next scan. One that no longer holds is reworded. A confirmed citation points at something that is gone, so an unchanged rewrite is rejected outright; reword the passage or point the citation at whatever replaced it.

Three fields on the envelope are easy to misread. truncated says this call left verification work behind and calling again makes more progress; it never means the queue is drained, and coverage is what knows that. paused means an operator has paused the ledger entirely, so the counts are from the last pass before the pause. And occurrences is read live beside the finding rather than recorded by the scan, so an empty occurrence list means you already did the work and the ledger has not caught up. Note also that only a call without a cursor does verification work; paging deeper reports the coverage the first page earned, because one walk is one act of looking.

The example shows the flow; live server validation inside run is authoritative for exact parameters.

Deleting an organization

Deletion is a three step lifecycle with a reversible middle, and the receipt is the state machine you follow. planOrganizationDeletion records an immutable, short-lived plan with a manifest and inventory totals, and changes nothing about the organization, so it is the safe way to see the scale of what a deletion would take and which blockers stand in the way. It takes a caller-minted UUIDv7 intentId; generate it on your own host and keep the literal, or with ids.mintOperationIds in a run of its own when the host cannot, where minting must be that run's only provider call, and reuse the same literal only when retrying that same plan. Reusing an intentId for a different organization is refused.

applyOrganizationDeletion is the consequential boundary. It takes the platform operationId from the plan receipt and the planToken passed through unchanged, and it must be called by the same user who created the plan. There is no separate confirmation step in v1; the receipt simply records that approval was satisfied without one. The moment it succeeds, ordinary writes are fenced, public content is hidden, and the quarantine connection sweep begins. From then on every other namespace, and every ordinary method here, refuses that organization with a lifecycle error until the deletion is cancelled.

Quarantine is reversible. cancelOrganizationDeletion restores active writer access and supersedes the remaining obligations, but only while the lifecycle is still deleting; once teardown claims it, cancellation is gone. getConsequentialActionReceipt reads the durable record without advancing anything, and its nextAction is the field to obey: it distinguishes apply, wait_for_quarantine, cancel_or_wait_for_teardown, wait_for_restoration, wait_for_teardown, create_new_plan, done, and the two states that no retry resolves, human_review_required and operator_intervention_required. Polling the receipt will never move a stuck deletion forward. Optionally, setOrganizationDeletionSuccessor records where the work is moving; that pointer survives onto the public tombstone, and passing null clears it.

The example shows the flow; live server validation inside run is authoritative for exact parameters.

For discovery, ask guide a direct question such as How do I invite someone to an organization?. For exact parameters, live server validation inside run is authoritative.