Creating documents and YouTube videos

These endpoints add content that is not a file you upload: a document you write in markdown, a document fetched from a public address, and a YouTube video. Each is one call. For a video or a guide you have as a file, see Uploading videos and Uploading guides.

They need a token granted the content:write scope, the same scope uploads use, which is an OAuth path today. The person behind the token must also be allowed to add that kind of content, checked on every call. They create content and nothing else: none of them edits or deletes something that already exists.

Who sees it, and whether it publishes

Every request names a visibility, the same three words GET /v1/content returns:

`visibility`	Who may see it
`everyone`	Everyone in the organization.
`teams`	The teams listed in `teamIds` (ids from `GET /v1/teams`).
`admins`	Administrators only.

teamIds is required with teams and refused with the other two. Every team has to belong to the organization: an id that is not one of its teams is a 400 with Unknown teamId.

For a document, the visibility also decides what happens to it, and the response tells you in mode:

`mode`	What it means
`published`	It went into the library with the visibility you asked for. It is still processing when the call returns: poll `GET /v1/content/{id}` with `contentId` until `processingStatus` and `indexingStatus` are both `COMPLETED`.
`review`	It is waiting for an administrator, who decides whether it belongs in the library and chooses who sees it. The visibility you sent is not kept. Follow it with `GET /v1/content-review-requests/{id}` and `reviewRequestId`. It is not readable through `/v1/content` until it is approved.

An organization admin publishes to any visibility. A team admin publishes to teams they manage and goes to review for anything wider, including admins, which is outside their teams. Anyone else who may submit content goes to review. This is the same rule the web app’s upload page follows.

Show the difference to whoever asked. “Your document is live” and “your document is with a reviewer” are not the same message.

Every contribution that goes to review emails the organization’s administrators, so one person may send at most 3 a minute and 20 an hour for review. That allowance is shared across both endpoints, the MCP tools and every connection the person has. Past it, the call is a 429 with REVIEW_SUBMISSION_LIMIT_REACHED, and nothing is created.

Create a document

POST /v1/documents

{
  "title": "Closing the store",
  "content": "# Closing the store\n\n1. Count the drawer...",
  "visibility": "teams",
  "teamIds": ["team_..."]
}

Field	Type	Notes
`title`	string	Required. Up to 255 characters, on one line. Line breaks and characters that change text direction are refused.
`content`	string	Required. The document, in markdown, up to 500,000 characters.
`visibility`	string	Required. `everyone`, `teams` or `admins`.
`teamIds`	string[]	With `teams` only. Up to 50.
`asDraft`	boolean	Leave it unpublished, for someone who may edit it to look over and publish in the app. Ignored when it goes to review.

{
  "mode": "published",
  "draft": false,
  "contentId": "…",
  "reviewRequestId": null,
  "title": "Closing the store",
  "url": "https://mereon.ai/documents/…/view"
}

draft is true when the document exists and is not live: you asked for a draft, or publishing failed after the document was made. Either way, do not create it again. Someone who may edit it can publish it from url.

Import a document from an address

POST /v1/documents/from-url

Fetches a public page or file, such as a PDF, and makes a document of it. Publishes or goes to review on the same rule as above, and returns the same shape. The title is the site’s name until processing reads a better one.

Only the public internet can be reached. An address that points at a private network, or at the cloud provider’s metadata service, is refused, and so is one that redirects there: each redirect is checked before it is followed. Every such refusal, and an address that cannot be reached at all, gives the same 400 with This address cannot be fetched, so the response says nothing about what is on a network you cannot see.

{
  "url": "https://example.com/handbook.pdf",
  "visibility": "everyone"
}

Field	Type	Notes
`url`	string	Required. An `http` or `https` address, up to 2,048 characters once percent-encoded, with no user name or password in it. Video sites are refused: use `POST /v1/videos/youtube` for YouTube.
`visibility`	string	Required.
`teamIds`	string[]	With `teams` only.

Add a YouTube video

POST /v1/videos/youtube

Adds a YouTube video to the library by its watch, share or shorts link. The video has to exist and allow embedding. There is no review lane, as in the web app: the person needs permission to add videos, and the visibility has to be one they may publish to, or the request is refused.

{
  "url": "https://www.youtube.com/watch?v=…",
  "visibility": "everyone"
}

{
  "contentId": "…",
  "alreadyInLibrary": false,
  "title": null,
  "url": "https://mereon.ai/videos/…/view"
}

title is null until processing reads it from YouTube. If the video is already in the organization’s library, nothing is created and alreadyInLibrary is true. Its visibility is left as it was, not changed to the one you sent. If the person cannot see that video, contentId, title and url are all null: the visibility on it is what keeps those from them.

Errors

Status	When
`400`	The body is invalid, `teamIds` does not match `visibility` or names a team outside the organization, the address cannot be fetched, or it is not a usable YouTube video. A team admin adding a YouTube video for `admins` also gets a `400` (`Please specify at least one team`), because admins only is wider than their teams and YouTube has no review lane.
`403`	The token lacks `content:write`, the person may not add this kind of content, or a team-scoped person named `everyone` or a team they do not manage for a YouTube video. A document never gets this for its visibility: it goes to review instead, if the person may submit.
`429`	Over the rate limit (`Retry-After` says when to try again), or over the review allowance above (the message says when).