Costruisci su Nonli con un riferimento API chiaro e pensato per l'IA.

5.1.Search brands

Return the brands visible to the API token role in the authenticated company.

5.2.Get a brand

Return one brand with optional embedded configuration used for publishing, shortlinks, smart images, and URL parameters.

6.1.Search social accounts

Return social accounts available to the authenticated company and user.

6.2.Get a social account

Return one connected social account with publishing metadata.

6.3.Get publishing quota

Return publishing quota information for selected social accounts before scheduling posts.

6.4.Get YouTube playlists

Return the playlists of connected YouTube social accounts, to choose the `youtube.playlistIds` of a YouTube post. Playlist items (videos) are not returned.

• IDs that are not YouTube social accounts of your company are silently left out of the response. When YouTube rejects the request for one account, its entry has an empty playlists array and an error message, and the other accounts are still returned.
• Playlists of every visibility are returned, with their privacyStatus. They are cached for one hour per account. The cache is cleared after a create, update, or delete through this API; a change made in YouTube Studio appears after the cache expires or with force=true. A playlist created moments ago can be missing from the list until YouTube exposes it: read the list again with force=true.

6.5.Create a YouTube playlist

Create a playlist on the channel of a connected YouTube social account. The API answers 201 Created with the new playlist. The API-token role must be allowed to manage social accounts. An unknown socialAccountId, or one that is not a YouTube account, returns 404 Not Found.

• Each call counts against the 24-hour limit of its own endpoint, including calls that fail. When the YouTube quota is exhausted the API returns 429 with a message such as "The YouTube quota is reached, please retry later."; this 429 does not come from the Nonli rate limiter and carries no Retry-After header. When the YouTube authorization of the account has expired the API returns 400 and the account must be reconnected.
• A playlist created through this API can be updated and deleted right away, even before YouTube exposes it everywhere. During that short delay the update response has a null itemCount and the playlist items endpoint returns an empty page.

6.6.Update a YouTube playlist

Change the title, description, or visibility of a playlist of a connected YouTube social account. Fields left out keep their current value. The API answers with the updated playlist.

• Each call counts against the 24-hour limit of its own endpoint, including calls that fail. When the YouTube quota is exhausted the API returns 429 with a message such as "The YouTube quota is reached, please retry later."; this 429 does not come from the Nonli rate limiter and carries no Retry-After header. When the YouTube authorization of the account has expired the API returns 400 and the account must be reconnected.
• A playlist that does not exist or belongs to another channel returns 404 Not Found.
• A playlist created through this API can be updated and deleted right away, even before YouTube exposes it everywhere. During that short delay the update response has a null itemCount and the playlist items endpoint returns an empty page.

6.7.Delete a YouTube playlist

Delete a playlist of a connected YouTube social account. The videos themselves are not deleted. The API answers 204 No Content.

• Each call counts against the 24-hour limit of its own endpoint, including calls that fail. When the YouTube quota is exhausted the API returns 429 with a message such as "The YouTube quota is reached, please retry later."; this 429 does not come from the Nonli rate limiter and carries no Retry-After header. When the YouTube authorization of the account has expired the API returns 400 and the account must be reconnected.
• A playlist that does not exist or belongs to another channel returns 404 Not Found.
• A playlist created through this API can be updated and deleted right away, even before YouTube exposes it everywhere. During that short delay the update response has a null itemCount and the playlist items endpoint returns an empty page.

6.8.List the videos of a YouTube playlist

Return one page of the videos of a YouTube playlist, in playlist order. The result is read from YouTube on each call and is not cached.

• Page through the playlist with pageToken: send the nextPageToken of the previous response until it is null. An unknown or inaccessible playlist returns 404 Not Found; a playlist created through this API moments ago returns an empty page instead.
• When the YouTube quota is exhausted the API returns 429 with a message such as "The YouTube quota is reached, please retry later."; this 429 does not come from the Nonli rate limiter and carries no Retry-After header. When the YouTube authorization of the account has expired the API returns 400 and the account must be reconnected.

6.9.Move a video in a YouTube playlist

Move a video to another position of a YouTube playlist. The API answers with the moved item and its new position.

• Each call counts against the 24-hour limit of its own endpoint, including calls that fail. When the YouTube quota is exhausted the API returns 429 with a message such as "The YouTube quota is reached, please retry later."; this 429 does not come from the Nonli rate limiter and carries no Retry-After header. When the YouTube authorization of the account has expired the API returns 400 and the account must be reconnected.
• The playlist must be sorted manually in YouTube: otherwise the call returns 400 Bad Request with a message such as "This playlist is not sorted manually in YouTube: set its order to manual before moving a video." A position beyond the end of the playlist also returns 400, and an unknown playlist or item returns 404 Not Found.

6.10.Get Pinterest boards

Return the boards of connected Pinterest social accounts, to choose the `pinterest.boardId` of a Pinterest post.

• IDs that are not Pinterest social accounts of your company are silently left out of the response. When Pinterest rejects the request for one account, its boards array is empty.
• Boards are cached for one hour per account; set force=true to read them from Pinterest again.

7.1.Search posts

Search the posts of your company in any status other than deleted or outdated: drafts, scheduled, published, and failed posts, and posts imported from connected accounts.

• Post-backed endpoints accept the documented post counters in counter filters and counter sorts, and responses echo the counter names the request used. Historical counter names replaced by public counter names are intentionally omitted.
• Without a status value in filters, posts of every status except 404 (deleted) and 410 (outdated) are returned, including drafts, scheduled posts, posts awaiting review, and failed publications. For figures consistent with published content, add filtersOr=status:200,203,204: published, publishing, and waiting to retry, the statuses of the "Published" group in the Nonli back office. Set withDeleted=true to also return deleted and outdated posts.
• Post status values: 200 published, 201 draft, 202 scheduled, 203 publishing, 204 waiting to retry publication, 210 awaiting review, 404 deleted, 410 outdated, 500 error, 503 publication error, 504 deletion error. Other codes are internal transitional or error states.
• A brandId value in filters or filtersOr selects the posts of the social accounts currently attached to that brand, whether they were published through Nonli or imported from the network: the brandId stored on each post is not used, so imported posts are included and an account moved to another brand takes its history with it. excludes=brandId: still tests the stored field and does not exclude imported posts.
• Posts that Nonli imports from connected accounts, because they were published directly on the network rather than through Nonli, have userId -5 and no brandId field.
• When a post published through Nonli has also been imported from the network as a separate post, Nonli removes the imported copy once the publication succeeds, so the post appears once. Duplicates created before this behavior shipped are not removed.
• Results cover the posts of the social accounts connected to your company that the token user can access, published through Nonli or imported from the network. An empty result usually means that the user has no access to the account, that Nonli has not imported posts from the account yet, or that a filter value, such as the network type or the publishedAt range, matches nothing. Posts of external accounts followed through Social Listening are not returned: search them with GET /listening/social.

7.2.Get a post

Return one post by ID with optional filters and field selection.

7.3.Get post categories

Return category aggregations used by post filters and dashboards.

• Post-backed endpoints accept the documented post counters in counter filters and counter sorts, and responses echo the counter names the request used. Historical counter names replaced by public counter names are intentionally omitted.

7.4.Get post brands

Return brand aggregations for posts visible to the API token role.

• Post-backed endpoints accept the documented post counters in counter filters and counter sorts, and responses echo the counter names the request used. Historical counter names replaced by public counter names are intentionally omitted.

7.5.Get post users

Return user aggregations for post author and collaboration filters.

• Post-backed endpoints accept the documented post counters in counter filters and counter sorts, and responses echo the counter names the request used. Historical counter names replaced by public counter names are intentionally omitted.

7.6.Get post languages

Return language aggregations for post filters.

• Post-backed endpoints accept the documented post counters in counter filters and counter sorts, and responses echo the counter names the request used. Historical counter names replaced by public counter names are intentionally omitted.

7.7.Get post histogram

Return time-bucketed post counts for graphing.

• Post-backed endpoints accept the documented post counters in counter filters and counter sorts, and responses echo the counter names the request used. Historical counter names replaced by public counter names are intentionally omitted.
• Without a status value in filters, posts of every status except 404 (deleted) and 410 (outdated) are counted, including drafts, scheduled posts, posts awaiting review, and failed publications. For figures consistent with published content, add filtersOr=status:200,203,204: published, publishing, and waiting to retry, the statuses of the "Published" group in the Nonli back office.
• A brandId value in filters or filtersOr selects the posts of the social accounts currently attached to that brand, whether they were published through Nonli or imported from the network: the brandId stored on each post is not used, so imported posts are included and an account moved to another brand takes its history with it. excludes=brandId: still tests the stored field and does not exclude imported posts.

7.8.Get post aggregation

Return generic aggregations for post dashboards and filter facets.

• Post-backed endpoints accept the documented post counters in counter filters and counter sorts, and responses echo the counter names the request used. Historical counter names replaced by public counter names are intentionally omitted.
• Without a status value in filters, posts of every status except 404 (deleted) and 410 (outdated) are counted, including drafts, scheduled posts, posts awaiting review, and failed publications. For figures consistent with published content, add filtersOr=status:200,203,204: published, publishing, and waiting to retry, the statuses of the "Published" group in the Nonli back office.
• A brandId value in filters or filtersOr selects the posts of the social accounts currently attached to that brand, whether they were published through Nonli or imported from the network: the brandId stored on each post is not used, so imported posts are included and an account moved to another brand takes its history with it. excludes=brandId: still tests the stored field and does not exclude imported posts.
• To list the custom tags in use, call GET /posts/aggregation?fields=customTag with a brandId filter: each row is a tag with its number of posts. Tags are case-sensitive. To read the list configured on a brand, call GET /brands/:brandId?fields=id,name,customTags,forceCustomTags.

7.9.Get post stats

Return aggregated post performance statistics for dashboard widgets.

• Post-backed endpoints accept the documented post counters in counter filters and counter sorts, and responses echo the counter names the request used. Historical counter names replaced by public counter names are intentionally omitted.
• This endpoint applies no default status filter: without a status filter, posts of every status are counted, including drafts, scheduled posts, failed publications, and deleted (404) or outdated (410) posts. For figures consistent with published content, add filtersOr=status:200,203,204: published, publishing, and waiting to retry, the statuses of the "Published" group in the Nonli back office.
• A brandId value in filters or filtersOr selects the posts of the social accounts currently attached to that brand, whether they were published through Nonli or imported from the network: the brandId stored on each post is not used, so imported posts are included and an account moved to another brand takes its history with it. excludes=brandId: still tests the stored field and does not exclude imported posts.

7.10.Check post content

Validate post content before publishing. The BO uses this endpoint to surface publication warnings.

7.11.Get post tags

Return the most used values of the post `tag` field that match a prefix, for autocomplete and reporting filters.

• Post-backed endpoints accept the documented post counters in counter filters and counter sorts, and responses echo the counter names the request used. Historical counter names replaced by public counter names are intentionally omitted.
• Only published posts (status 200) are counted.
• This endpoint aggregates the tag field, not customTag: tags written in customTag are not returned. To list the custom tags in use, call GET /posts/aggregation?fields=customTag with a brandId filter: each row is a tag with its number of posts. Tags are case-sensitive. To read the list configured on a brand, call GET /brands/:brandId?fields=id,name,customTags,forceCustomTags.
• Prefix matching is case-sensitive.

7.12.Get post topics

Return the most used post topics that match a prefix, for autocomplete and reporting filters.

• Post-backed endpoints accept the documented post counters in counter filters and counter sorts, and responses echo the counter names the request used. Historical counter names replaced by public counter names are intentionally omitted.
• Only published posts (status 200) are counted. Prefix matching is case-sensitive.

7.13.Create posts in bulk

Create one or more posts: submit them for review, publish them immediately, or schedule them. The API-token role must grant `post.write` and access to every requested brand and social account.

• Post status is constrained by the API-token role. review always remains pending validation, and read access to the target is sufficient to create a post for review. A publish request is automatically downgraded to review when the role cannot publish directly. Tokens without post.write or access to the requested resources are rejected.
• The creator identity is server-managed. Posts created with a Bearer token use API <token name> as author and have no userId. Client-supplied author identity fields are ignored, so an API integration cannot impersonate a Nonli user.
• When the brand has forceCustomTags enabled, a request that attaches a customTag value absent from the brand customTags list fails as a whole with 400 Bad Request, and no post is written. Matching is exact and case-sensitive. Tags already stored on an updated post are accepted. Add the tag to the brand list first, with PUT /brands/:brandId and the complete customTags array, which replaces the stored list.
• When a post published through Nonli has also been imported from the network as a separate post, Nonli removes the imported copy once the publication succeeds, so the post appears once. Duplicates created before this behavior shipped are not removed.
• Build a thread sequentially. Set thread.activated=true on every segment. The root omits isChild, parent, and origin; every later segment sets isChild=true, parent to the immediately previous segment ID, and origin to the root ID. For the first child, parent and origin therefore have the same root ID. After adding each child, read the root and verify its ordered thread.children list: a successful HTTP response alone does not prove that the chain is complete.
• On networks with first-comment support, put the article link in post.comment. Threads and Bluesky do not publish a native first comment, so a hand-built chain must instead attach the shortlink to the root with shortlink.mappingId and put the resolved public URL only in the final segment message. Create that final segment without the URL, update it with the root response values https://ROOT_SHORT_DOMAIN/ROOT_SHORT_ID, then read the root and final segment back before publication. Do not also place that URL in a root first comment.
• On Threads and Bluesky, Nonli can automatically convert an active first comment into the first child when the root has neither an activated thread nor existing children. [SHORTLINK] is expanded only during that conversion and only when the first comment has a shortlink. It is not expanded in segments created directly through /posts/bulk; hand-built segments must contain the resolved URL.
• Validate every segment against its destination network before creating the chain. Threads currently allows 500 characters per segment; Bluesky allows 300 graphemes. Mentions and links contribute to those limits, including the resolved shortlink added to the final segment.

7.14.Update posts in bulk

Update a collection of posts. Send post.id and, when available, createdAt to optimize lookup.

• Send each post with id, its createdAt when known, and only the fields you change. createdAt locates the post and is never modified; send it as returned by the API, with or without milliseconds. Accepted post fields: socialAccount (externalId, publisherId, type, subType), brandId, tag, customTag, postType, subType, shortlink.mappingId, source.documentId, title, message, description, image, video, media, schedule (startDate, endDate), publishedAt, createdAt, breakingNews, callToAction, shortId, comment (activated, message, pictureUrl), status, isAiGenerated, sponsor, location, geoblocking.country, commentEnabled, duetEnabled, stitchEnabled, madeForKids, threads, visibility, collaborator, pinterest.boardId, youtube.playlistIds, commercialContent, and tiktok.anchor. Each video item accepts url, mappingId, embed, sourceExternalId, title, tag, thumbnail, shareToFeed, isAiGenerated, duration, height, width, and size.
• Any other key, at any level, makes the whole request fail with 400 Bad Request and an "Unexpected item(s)" message. This includes read-only fields returned by GET /posts/:postId, such as socialAccount fields other than externalId, publisherId, type, and subType, or video[].externalId: do not send back a post object read from the API unchanged.
• Submitted schedule, publishedAt, shortId, and status values are either applied or rejected with a reason: the API never answers 200 while leaving one of them unapplied. A request that updates a single post and is rejected answers 409 Conflict with the reason in the JSON body, for example {"messages":{"errors":["The publication date (publishedAt) is in the past"]}}, and nothing is updated; an error that has its own status, such as 403, 404, or 423, keeps it. In a request that updates several posts the API answers 200: a rejected post is returned as its id and an error message only, and the other posts are updated. A post whose update failed on an internal error is also returned as its id and error, with a 200 answer, even alone.
• Scheduling a post that is not published yet: publishedAt alone moves the publication to that date and extends the schedule range to contain it; schedule.startDate without endDate is a fixed publication date; an empty schedule object publishes now. A new publishedAt that is not in the future is rejected with 409, unless the post is published now or the value lies inside a schedule range sent in the same request. An endDate before the startDate, or a schedule ending more than 2 minutes in the past, is rejected with 409. When the schedule of a post that is not published has already elapsed, content changes are saved without rescheduling it, and the returned post carries an error field; a shortId change, a status change, or any update of a post awaiting review is rejected with 409 until a new schedule is sent.
• On a post already published, a different publishedAt or different schedule dates are rejected with 409. Once publication has started (status 203, 204, or 200), changing postType or the shortlink is rejected with 409 as well. A publishedAt, postType, or shortlink change that can no longer be made fails the whole request with 409, even when the request updates several posts. A status of review that the post can no longer take is rejected with 409; API tokens cannot send draft, which fails the whole request with 400. An invalid shortId, or one already in use, is rejected with 409.
• When the brand has forceCustomTags enabled, a request that attaches a customTag value absent from the brand customTags list fails as a whole with 400 Bad Request, and no post is written. Matching is exact and case-sensitive. Tags already stored on an updated post are accepted. Add the tag to the brand list first, with PUT /brands/:brandId and the complete customTags array, which replaces the stored list.
• There is no maximum number of posts per call, and one call counts as one call against the rate limit whatever the number of posts. A very large batch can exceed the server time limits and fail, so split large batches into several calls.
• After an update has been applied, the same post cannot be updated again for 3 seconds: a request on it during that time fails as a whole with 423 Locked, a Retry-After header giving the real number of seconds left, and a JSON body such as {"messages":{"errors":["The post is being edited, please try again in 3s."]}}. Wait for that number of seconds, then send the request again. While another update of the post is still running, the delay can reach 30 seconds. A request in which no post was updated holds no lock: the corrected request can be sent at once. A post being published also answers 423, without Retry-After: retry a few seconds later.
• With updatePostOnNetwork=false, Nonli updates the post in Nonli only and sends nothing to the social network: no update of an already published post and no Facebook crosspost preparation. The trace of a published post then records "Update post in Nonli only, not sent to social network" instead of "Update post in social network". The flag concerns the update itself: it does not cancel the publication of a post that is not published yet, which stays in the publication scheduler and is published at its scheduled date. With updatePostOnNetwork=false, YouTube playlists are not changed either.
• On a published YouTube video updated on the network (updatePostOnNetwork left to true), sending youtube.playlistIds synchronizes the playlists that Nonli manages for this post: the IDs sent now and the IDs previously stored on the post. Nonli adds the video to a requested playlist only when YouTube reports it absent, so no duplicate entry is created, and removes it from a previously stored playlist that is no longer requested. Playlists the video was added to outside Nonli are never changed. Omit youtube.playlistIds to leave playlists untouched; send an empty array to remove the video from the stored playlists. A playlist error does not fail the update: it is recorded in the post trace.
• Updating a published YouTube video without visibility does not reset it to a default: Nonli sends the visibility stored on the post, or keeps the one YouTube holds when none is stored. On a post already published, the network ID of each video is kept whatever video[].url is sent.

7.15.Delete posts in bulk

Delete a collection of posts. The async flag can be used for background deletion.

8.1.Search shortlinks

Search shortlinks and retrieve counters, target URLs, metadata, and publication information.

• Shortlink counter endpoints accept shortlink counters only, currently click. Post counters such as engagement, reach, or videoViews are invalid for Shortlinks.

8.2.Get a shortlink

Return one shortlink by ID with optional counters and field selection.

• Shortlink counter endpoints accept shortlink counters only, currently click. Post counters such as engagement, reach, or videoViews are invalid for Shortlinks.

8.3.Get shortlink stats

Return aggregated shortlink performance statistics.

• Shortlink counter endpoints accept shortlink counters only, currently click. Post counters such as engagement, reach, or videoViews are invalid for Shortlinks.

8.4.Get shortlink authors

Return author aggregations used by shortlink filters.

• Shortlink counter endpoints accept shortlink counters only, currently click. Post counters such as engagement, reach, or videoViews are invalid for Shortlinks.

8.5.Get shortlink brands

Return brand aggregations used by shortlink filters.

• Shortlink counter endpoints accept shortlink counters only, currently click. Post counters such as engagement, reach, or videoViews are invalid for Shortlinks.

8.6.Create a shortlink

Create or extract a shortlink for a target URL.

8.7.Create shortlinks in bulk

Create several shortlinks in one request.

8.8.Update a shortlink

Update target URL, metadata, images, brand association, and sponsor information for a shortlink.