Developer API v2.1

Build on Nonli with a clean, AI-ready API reference.

Use API tokens, search posts and listening data, create shortlinks, publish posts, and upload videos from one documented surface.

OpenAPI JSON llms.txt

Base URL

https://api.nonli.com/v2.1

65endpoints

11resources

Quick start

Three habits are enough to authenticate, keep payloads small, and query production data predictably.

bash

1curl --location 'https://api.nonli.com/v2.1/brands?size=1&fields=id,name' \
2  --header 'Authorization: Bearer YOUR_API_TOKEN'

Create an API token

Company administrators create and rotate API tokens from the Nonli back office.

Send the Bearer header

Send the token on every authenticated request using Authorization: Bearer YOUR_API_TOKEN. To validate a token, call the brands endpoint shown here.

Request exact fields

Use fields, filters, filtersOr, excludes, size, page, and sort to keep responses small for both apps and AI agents.

AI integration notes

OpenAPI JSON: /api-docs/openapi.json

llms.txt: /llms.txt

Prefer /api-docs/openapi.json for tool generation and schema extraction.
Use /llms.txt for a compact crawlable entry point.
API tokens are company-role credentials, not web user sessions: do not use /me with Bearer tokens.
Use the fields parameter whenever possible to reduce token usage.
Respect endpoint rate limits and page through large datasets.

Endpoint explorer

65 endpoints

GETSearch brands/brandsOpen GETGet a brand/brands/:brandIdOpen GETSearch social accounts/social-accountsOpen GETGet a social account/social-accounts/:socialAccountIdOpen GETGet publishing quota/social-accounts/publishing-quotaOpen GETGet YouTube playlists/social-accounts/youtube/playlistsOpen GETGet Pinterest boards/social-accounts/pinterest/boardsOpen GETSearch posts/postsOpen GETGet a post/posts/:postIdOpen GETGet post categories/posts/categoriesOpen GETGet post brands/posts/brandsOpen GETGet post users/posts/usersOpen GETGet post languages/posts/languagesOpen GETGet post histogram/posts/histogramOpen GETGet post aggregation/posts/aggregationOpen GETGet post stats/posts/statsOpen POSTCheck post content/posts/checkOpen GETGet post tags/posts/tagsOpen GETGet post topics/posts/topicsOpen POSTCreate posts in bulk/posts/bulkOpen PUTUpdate posts in bulk/posts/bulkOpen DELETEDelete posts in bulk/posts/bulkOpen GETSearch shortlinks/shortlinksOpen GETGet a shortlink/shortlinks/:shortlinkIdOpen GETGet shortlink stats/shortlinks/statsOpen GETGet shortlink authors/shortlinks/authorsOpen GETGet shortlink brands/shortlinks/brandsOpen POSTCreate a shortlink/shortlinksOpen POSTCreate shortlinks in bulk/shortlinks/bulkOpen PUTUpdate a shortlink/shortlinks/:shortlinkIdOpen POSTGenerate a message for a shortlink/shortlinks/:shortlinkId/generate-messageOpen GETSearch themes/themesOpen GETGet a theme/themes/:themeIdOpen POSTCreate a theme/themesOpen PUTUpdate a theme/themes/:themeIdOpen DELETEDelete a theme/themes/:themeIdOpen GETGet theme roles/themes/rolesOpen GETGet social listening/listening/socialOpen GETGet organic listening/listening/organicOpen GETGet organic content/listening/organic/:organicIdOpen GETGet organic stats/listening/organic/statsOpen GETGet organic aggregation/listening/organic/aggregationOpen GETSuggest organic filter values/listening/organic/suggest/:fieldOpen GETGet the leaderboard/posts/leaderboardOpen POSTSearch the leaderboard/posts/leaderboard/_searchOpen GETGet leaderboard categories/posts/leaderboard/categoriesOpen GETSearch accounts/accountsOpen POSTAdd an account/accountsOpen GETGet account categories/accounts/categoriesOpen GETSearch account locations/accounts/locationsOpen GETGet account stats/accounts/statsOpen GETSearch bots/botsOpen GETGet a bot/bots/:botIdOpen POSTCreate bots in bulk/bots/bulkOpen PUTUpdate bots in bulk/bots/bulkOpen DELETEDelete a bot/bots/:botIdOpen GETGet bot configuration info/bots/infoOpen GETSearch media/mediaOpen GETGet media tags/media/tagsOpen POSTUpload an image/upload/imageOpen POSTCreate upload video token/upload/video/tokenOpen POSTCheck uploaded video existence/upload/video/existsOpen POSTUpload video chunk/upload/video/chunkOpen POSTCreate upload document token/upload/document/tokenOpen POSTUpload document chunk/upload/document/chunkOpen

Common integration flows

5 endpoints

GET/brands

Search brands

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

GET/posts

Search posts

Search posts published or scheduled through Nonli.

POST/posts/bulk

Create posts in bulk

Create a collection of posts. Use postType "flying" with a shortlink mappingId to publish a flying link.

POST/shortlinks

Create a shortlink

Create or extract a shortlink for a target URL.

GET/listening/social

Get social listening

Search social posts and counters collected from supported social networks.

On this page

1.Conventions

Shared rules that apply across every endpoint.

Authentication

Send an API token in the Authorization header on every authenticated call: Authorization: Bearer YOUR_API_TOKEN. API tokens represent a company role, not a web user session, so /me is not available with Bearer tokens. Store tokens securely, rotate them from the back office, and never put them in query strings.

Pagination

List endpoints return total plus a rows array. Page through results with size and a zero-based page until you have collected total items. Use fields to keep each item small.

Dates and timezones

Timestamps are UTC in ISO-8601, for example 2026-05-27T23:59:59Z. Date-range filters use ".." between two values, for example publishedAt:-30 days..now.

Identifiers

Posts, shortlinks, and organic items use string UUIDs. Brands, social accounts, and themes use integer IDs. Pass identifiers exactly as the API returns them.

Counter names

For post-backed endpoints, use the documented counter names in sort, filters, filtersOr, excludes, bot trigger counters, and bot post-rate metrics. Organic Listening and Shortlink endpoints expose their own counters and reject post counters with 400 Bad Request.

2.Search parameters

Most list endpoints share the same query grammar.

Field	Type	Description
`size`	`int`	Maximum number of results to return.Default: `20 or endpoint-specific`
`page`	`int`	Zero-based page number.Default: `0`
`q`	`string`	Full-text search query.
`qf`	`string`	Comma-separated fields used by the full-text query.
`sort`	`string`	Sort expression. Prefix a field with "-" for descending order. Counter-backed endpoints can sort by counters.total.<field> or by the counter shorthand itself, for example sort=-engagement on post/social data or sort=-click on organic data.
`filters`	`string`	AND filters on item fields. Use semicolons between filters and ".." for ranges. Send the separators ":", ";", "," and ".." as raw characters: search endpoints read the raw query string and treat percent-encoded separators as literal value characters. Percent-encode only characters inside values, such as spaces (%20). On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203". On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`excludes`	`string`	Exclude results when a field contains a value. On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`fields`	`string`	Comma-separated fields to include in each returned item.
`exists`	`string`	Comma-separated fields that must exist in each returned item. Fields must belong to the endpoint entity; invalid fields return 400 Bad Request.

3.Available counters

Use this list as the public counter surface per endpoint family. Historical counter names that have been replaced are intentionally omitted.

Posts, Social Listening, and Bots

/posts/posts/categories/posts/brands/posts/users/posts/languages/posts/histogram/posts/aggregation/posts/stats/posts/tags/posts/topics/posts/leaderboard/posts/leaderboard/_search/posts/leaderboard/categories/listening/social/bots/bulk

Counters

clickclick_uniquectrengagementfacebook_engagement_per_minuteweighted_facebook_engagementweighted_facebook_engagement_per_minutefacebook_commentfacebook_total_reactionfacebook_sharereachimpressionvideoViewsvideo_views_3secfacebook_post_video_avg_time_watchedvideo_completion_rateoverperformingrepostsquotesmonetizationsnapchat_screenshotssubscriberfacebook_link_clicksfacebook_other_clicksfacebook_photo_viewfacebook_video_playfacebook_post_video_views_60s_excludes_shorterinstagram_savedinstagram_total_interactionsinstagram_clips_replays_countlinkedin_private_click_countyoutube_likesyoutube_dislikesyoutube_estimated_minutes_watched

Note: Use these names in post-backed counter filters, counter sorts, bot trigger counters, and bot post-rate metrics. Facebook reach is requested as reach; the API maps the current Meta reach metric internally. TikTok metrics currently feed the common post counters engagement, facebook_total_reaction, facebook_comment, facebook_share, videoViews, and impression, instead of dedicated TikTok counters. Historical counter names replaced by these public names, and counters that are no longer available from network APIs, are intentionally omitted.

Organic Listening

/listening/organic/listening/organic/stats/listening/organic/aggregation

Counters

clicknew_leadquantityamountpaywall_viewpaywall_unlockedpaywall_clickpaywall_subscribe_clickpaywall_login_clicksubscription_completecomment_countvideo_viewsview_in_stockview_out_of_stockpriceprice_variationlow_pricehigh_priceratingreview_countstock

Note: Use these names for standard Organic Listening counter filters and sorts. Legacy Organic counters are intentionally excluded from the public API surface.

Shortlinks

/shortlinks/shortlinks/:shortlinkId/shortlinks/stats/shortlinks/authors/shortlinks/brands

Counters

click

Note: Shortlink counter endpoints only expose shortlink counters and reject post counters.

Accounts

/accounts/accounts/stats

Counters

follower_count

Note: Use the full counter path on Accounts endpoints, for example sort=-counters.total.follower_count or filters=counters.graph.counter:follower_count. The counter sort shorthand (sort=-follower_count) also resolves. The documented name is resolved to the stored account counter internally; historical internal counter names are intentionally omitted. Post counters such as engagement, reach, or videoViews are invalid for Accounts.

4.Errors

Branch on the HTTP status code rather than parsing error message text. Status codes carry their standard HTTP meaning.

Status	Meaning
`200`OK	The request succeeded.
`400`Bad request	The payload or query parameters were malformed or failed validation.
`401`Unauthorized	The Authorization Bearer token is missing or invalid. Check the token value or rotate it from the back office before replaying the call.
`403`Forbidden	The API token is valid but lacks permission for this resource.
`404`Not found	The resource does not exist or is not visible to your company.
`429`Too many requests	A rate limit was reached. Slow down and retry later.
`500`Server error	Unexpected server error. Retry idempotent reads with backoff.

Error responses return a JSON body that describes the problem, but the HTTP status code is the contract: build error handling around the status code, not the message text.

Handling guidance

Treat any non-2xx status as a failure and read the JSON body for context.
On 401, check the API token value, rotate it if needed, and replay the request.
On 429, back off before retrying, and respect a Retry-After header when one is present.
On 5xx, retry idempotent reads with exponential backoff.

Reference

5.Brands

2 endpoints

Read the brands attached to the authenticated company. Brand IDs are required by publishing and shortlink workflows.

GET/brandsBearer required

5.1.Search brands

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

Query parameters

Field	Type	Description
`size`	`int`	Count of results to return.Default: `50`
`page`	`int`	Zero-based page number.Default: `0`
`sort`	`string`	Sort expression.Default: `-id`
`q`	`string`	Full-text search query.
`qf`	`string`	Comma-separated fields used by the full-text query.
`filters`	`string`	AND filters on item fields. Use semicolons between filters and ".." for ranges. Send the separators ":", ";", "," and ".." as raw characters: search endpoints read the raw query string and treat percent-encoded separators as literal value characters. Percent-encode only characters inside values, such as spaces (%20). On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203". On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`excludes`	`string`	Exclude results when a field contains a value. On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`fields`	`string`	Comma-separated fields to include in each returned item.
`exists`	`string`	Comma-separated fields that must exist in each returned item. Fields must belong to the endpoint entity; invalid fields return 400 Bad Request.
`embed`	`string`	Can embed urlParameters, domains, geoblocking, smart image configs, smart message configs, and URLs to stalk.

Response fields

Field	Type	Description
`total`	`int`	Total number of items found.
`rows`	`Brand[]`	Brands found on the requested page.
->`id`	`int`	Unique brand ID.
->`name`	`string`	Brand name.
->`shortDomain`	`string`	Brand short domain.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/brands?fields=id,name,shortDomain&size=50' \
2  --header 'Authorization: Bearer YOUR_API_TOKEN'

GET/brands/:brandIdBearer required

5.2.Get a brand

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

Query parameters

Field	Type	Description
`fields`	`string`	Comma-separated fields to include.
`embed`	`string`	Can embed urlParameters, domains, geoblocking, smart image configs, smart message configs, and URLs to stalk.

Response fields

Field	Type	Description
`id`	`int`	Unique brand ID.
`name`	`string`	Brand name.
`shortDomain`	`string`	Brand short domain.
`domains`	`BrandDomain[]`	Configured brand domains when embedded.
`urlParameters`	`object[]`	URL parameter configuration when embedded.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/brands/1?fields=id,name,shortDomain&embed=domains,urlParameters' \
2  --header 'Authorization: Bearer YOUR_API_TOKEN'

6.Social accounts

5 endpoints

Read connected social accounts and quota data required before creating or scheduling posts.

GET/social-accountsBearer required

6.1.Search social accounts

Return social accounts available to the authenticated company and user.

Query parameters

Field	Type	Description
`size`	`int`	Count of results to return.Default: `50`
`page`	`int`	Zero-based page number.Default: `0`
`q`	`string`	Full-text search query.
`qf`	`string`	Comma-separated fields used by the full-text query.
`sort`	`string`	Sort expression. Prefix a field with "-" for descending order. Counter-backed endpoints can sort by counters.total.<field> or by the counter shorthand itself, for example sort=-engagement on post/social data or sort=-click on organic data.
`filters`	`string`	AND filters on item fields. Use semicolons between filters and ".." for ranges. Send the separators ":", ";", "," and ".." as raw characters: search endpoints read the raw query string and treat percent-encoded separators as literal value characters. Percent-encode only characters inside values, such as spaces (%20). On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203". On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`excludes`	`string`	Exclude results when a field contains a value. On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`fields`	`string`	Comma-separated fields to include in each returned item.
`exists`	`string`	Comma-separated fields that must exist in each returned item. Fields must belong to the endpoint entity; invalid fields return 400 Bad Request.
`embed`	`string`	Optional related data to embed.

Response fields

Field	Type	Description
`total`	`int`	Total number of items found.
`rows`	`SocialAccount[]`	Social accounts found on the requested page.
->`id`	`int`	Social account ID.
->`externalId`	`string`	Social network account/page ID.
->`name`	`string`	Account display name.
->`type`	`string`	Network type: facebook, linkedin, instagram, etc.
->`brandId`	`int`	Associated brand ID.
->`status`	`string`	Connection or publishing status.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/social-accounts?filters=brandId:1&type=facebook&fields=id,name,type,externalId,brandId,status&size=50' \
2  --header 'Authorization: Bearer YOUR_API_TOKEN'

GET/social-accounts/:socialAccountIdBearer required

6.2.Get a social account

Return one connected social account with publishing metadata.

Query parameters

Field	Type	Description
`fields`	`string`	Comma-separated fields to include.

Response fields

Field	Type	Description
`id`	`int`	Social account ID.
`externalId`	`string`	Social network account/page ID.
`name`	`string`	Account display name.
`type`	`string`	Network type.
`brandId`	`int`	Associated brand ID.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/social-accounts/42?fields=id,name,type,externalId,brandId' \
2  --header 'Authorization: Bearer YOUR_API_TOKEN'

GET/social-accounts/publishing-quotaBearer required

6.3.Get publishing quota

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

Query parameters

Field	Type	Description
`socialAccounts`	`string`	Comma-separated social account IDs or formatted account descriptors.

Response fields

Field	Type	Description
`quota`	`object`	Quota information grouped by account or network.
`usage`	`object`	Current usage grouped by account or network.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/social-accounts/publishing-quota?socialAccounts=42,43' \
2  --header 'Authorization: Bearer YOUR_API_TOKEN'

GET/social-accounts/youtube/playlistsBearer required

6.4.Get YouTube playlists

Return YouTube playlists for connected YouTube social accounts.

Query parameters

Field	Type	Description
`size`	`int`	Maximum number of results to return.Default: `20 or endpoint-specific`
`page`	`int`	Zero-based page number.Default: `0`
`q`	`string`	Full-text search query.
`qf`	`string`	Comma-separated fields used by the full-text query.
`sort`	`string`	Sort expression. Prefix a field with "-" for descending order. Counter-backed endpoints can sort by counters.total.<field> or by the counter shorthand itself, for example sort=-engagement on post/social data or sort=-click on organic data.
`filters`	`string`	AND filters on item fields. Use semicolons between filters and ".." for ranges. Send the separators ":", ";", "," and ".." as raw characters: search endpoints read the raw query string and treat percent-encoded separators as literal value characters. Percent-encode only characters inside values, such as spaces (%20). On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203". On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`excludes`	`string`	Exclude results when a field contains a value. On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`fields`	`string`	Comma-separated fields to include in each returned item.
`exists`	`string`	Comma-separated fields that must exist in each returned item. Fields must belong to the endpoint entity; invalid fields return 400 Bad Request.

Response fields

Field	Type	Description
`total`	`int`	Total number of playlists found.
`rows`	`object[]`	YouTube playlists available for publishing options.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/social-accounts/youtube/playlists?filters=socialAccountId:42&size=50' \
2  --header 'Authorization: Bearer YOUR_API_TOKEN'

GET/social-accounts/pinterest/boardsBearer required

6.5.Get Pinterest boards

Return Pinterest boards for connected Pinterest social accounts.

Query parameters

Field	Type	Description
`size`	`int`	Maximum number of results to return.Default: `20 or endpoint-specific`
`page`	`int`	Zero-based page number.Default: `0`
`q`	`string`	Full-text search query.
`qf`	`string`	Comma-separated fields used by the full-text query.
`sort`	`string`	Sort expression. Prefix a field with "-" for descending order. Counter-backed endpoints can sort by counters.total.<field> or by the counter shorthand itself, for example sort=-engagement on post/social data or sort=-click on organic data.
`filters`	`string`	AND filters on item fields. Use semicolons between filters and ".." for ranges. Send the separators ":", ";", "," and ".." as raw characters: search endpoints read the raw query string and treat percent-encoded separators as literal value characters. Percent-encode only characters inside values, such as spaces (%20). On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203". On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`excludes`	`string`	Exclude results when a field contains a value. On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`fields`	`string`	Comma-separated fields to include in each returned item.
`exists`	`string`	Comma-separated fields that must exist in each returned item. Fields must belong to the endpoint entity; invalid fields return 400 Bad Request.

Response fields

Field	Type	Description
`total`	`int`	Total number of boards found.
`rows`	`object[]`	Pinterest boards available for publishing options.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/social-accounts/pinterest/boards?filters=socialAccountId:42&size=50' \
2  --header 'Authorization: Bearer YOUR_API_TOKEN'

7.Posts

15 endpoints

Search, create, update, and delete social posts. Bulk write endpoints accept arrays so integrations can synchronize several posts at once.

GET/postsBearer required

7.1.Search posts

Search posts published or scheduled through Nonli.

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.

Rate limit720 calls every 12 hours for API users

Query parameters

Field	Type	Description
`size`	`int`	Count of results to return.Default: `20`
`page`	`int`	Zero-based page number.Default: `0`
`q`	`string`	Full-text search query.
`qf`	`string`	Comma-separated fields used by the full-text query.
`sort`	`string`	Sort expression. Prefix a field with "-" for descending order. Counter-backed endpoints can sort by counters.total.<field> or by the counter shorthand itself, for example sort=-engagement on post/social data or sort=-click on organic data.
`filters`	`string`	AND filters on item fields. Use semicolons between filters and ".." for ranges. Send the separators ":", ";", "," and ".." as raw characters: search endpoints read the raw query string and treat percent-encoded separators as literal value characters. Percent-encode only characters inside values, such as spaces (%20). On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203". On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`excludes`	`string`	Exclude results when a field contains a value. On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`fields`	`string`	Comma-separated fields to include in each returned item.
`exists`	`string`	Comma-separated fields that must exist in each returned item. Fields must belong to the endpoint entity; invalid fields return 400 Bad Request.
`withDeleted`	`bool`	Include deleted posts in the results.
`embed`	`string`	Allowed value: sharedPost.

Response fields

Field	Type	Description
`total`	`int`	Total number of items found.
`rows`	`Post[]`	Posts found on the requested page.
->`author`	`string`	Post author.
->`createdAt`	`date`	Creation date in UTC format.
->`updatedAt`	`date`	Last update date in UTC format.
->`publishedAt`	`date`	Publication date in UTC format.
->`message`	`string`	Post message.
->`postType`	`string`	Post type: text, link, photo, album, video, flying, reel, document, etc.
->`socialAccount`	`SocialAccount`	Target social account.
->`status`	`int`	Post status.
->`counters.total`	`CounterTotal[]`	Aggregated counters.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/posts?q=tag:politique&size=20&page=0&fields=author,createdAt,updatedAt,message,postType,publishedAt,socialAccount,status,title&sort=-publishedAt,createdAt&filters=brandId:1;status:200' \
2  --header 'Authorization: Bearer YOUR_API_TOKEN'

GET/posts/:postIdBearer required

7.2.Get a post

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

Query parameters

Field	Type	Description
`fields`	`string`	Comma-separated fields to include.
`filters`	`string`	Optional filters used to optimize lookup, such as createdAt.
`embed`	`string`	Optional related data to embed.

Response fields

Field	Type	Description
`id`	`string`	Post ID.
`createdAt`	`date`	Creation date.
`publishedAt`	`date`	Publication date.
`message`	`string`	Post message.
`postType`	`string`	Post type.
`socialAccount`	`SocialAccount`	Target social account.
`status`	`int`	Post status.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/posts/4283ab2d-e3dd-7b1a-7cd6-bbcc71e1xxxx?fields=id,message,postType,publishedAt,socialAccount,status' \
2  --header 'Authorization: Bearer YOUR_API_TOKEN'

GET/posts/categoriesBearer required

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.

Query parameters

Field	Type	Description
`size`	`int`	Maximum number of results to return.Default: `20 or endpoint-specific`
`q`	`string`	Full-text search query.
`qf`	`string`	Comma-separated fields used by the full-text query.
`filters`	`string`	AND filters on item fields. Use semicolons between filters and ".." for ranges. Send the separators ":", ";", "," and ".." as raw characters: search endpoints read the raw query string and treat percent-encoded separators as literal value characters. Percent-encode only characters inside values, such as spaces (%20). On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203". On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`excludes`	`string`	Exclude results when a field contains a value. On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`exists`	`string`	Comma-separated fields that must exist in each returned item. Fields must belong to the endpoint entity; invalid fields return 400 Bad Request.

Response fields

Field	Type	Description
`total`	`int`	Total number of categories found.
`rows.key`	`string`	Category value.
`rows.doc_count`	`int`	Number of posts in the category.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/posts/categories?filters=brandId:1&size=100' \
2  --header 'Authorization: Bearer YOUR_API_TOKEN'

GET/posts/brandsBearer required

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.

Query parameters

Field	Type	Description
`size`	`int`	Maximum number of results to return.Default: `20 or endpoint-specific`
`q`	`string`	Full-text search query.
`qf`	`string`	Comma-separated fields used by the full-text query.
`filters`	`string`	AND filters on item fields. Use semicolons between filters and ".." for ranges. Send the separators ":", ";", "," and ".." as raw characters: search endpoints read the raw query string and treat percent-encoded separators as literal value characters. Percent-encode only characters inside values, such as spaces (%20). On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203". On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`excludes`	`string`	Exclude results when a field contains a value. On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`exists`	`string`	Comma-separated fields that must exist in each returned item. Fields must belong to the endpoint entity; invalid fields return 400 Bad Request.

Response fields

Field	Type	Description
`total`	`int`	Total number of brands found.
`rows.key`	`string`	Brand identifier or name.
`rows.doc_count`	`int`	Number of posts for the brand.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/posts/brands?filters=publishedAt:-30%20days..now&size=100' \
2  --header 'Authorization: Bearer YOUR_API_TOKEN'

GET/posts/usersBearer required

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.

Query parameters

Field	Type	Description
`size`	`int`	Maximum number of results to return.Default: `20 or endpoint-specific`
`q`	`string`	Full-text search query.
`qf`	`string`	Comma-separated fields used by the full-text query.
`filters`	`string`	AND filters on item fields. Use semicolons between filters and ".." for ranges. Send the separators ":", ";", "," and ".." as raw characters: search endpoints read the raw query string and treat percent-encoded separators as literal value characters. Percent-encode only characters inside values, such as spaces (%20). On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203". On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`excludes`	`string`	Exclude results when a field contains a value. On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`exists`	`string`	Comma-separated fields that must exist in each returned item. Fields must belong to the endpoint entity; invalid fields return 400 Bad Request.

Response fields

Field	Type	Description
`total`	`int`	Total number of users found.
`rows.key`	`string`	User identifier or name.
`rows.doc_count`	`int`	Number of posts for the user.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/posts/users?filters=brandId:1&size=100' \
2  --header 'Authorization: Bearer YOUR_API_TOKEN'

GET/posts/languagesBearer required

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.

Query parameters

Field	Type	Description
`size`	`int`	Maximum number of results to return.Default: `20 or endpoint-specific`
`q`	`string`	Full-text search query.
`qf`	`string`	Comma-separated fields used by the full-text query.
`filters`	`string`	AND filters on item fields. Use semicolons between filters and ".." for ranges. Send the separators ":", ";", "," and ".." as raw characters: search endpoints read the raw query string and treat percent-encoded separators as literal value characters. Percent-encode only characters inside values, such as spaces (%20). On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203". On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`excludes`	`string`	Exclude results when a field contains a value. On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`exists`	`string`	Comma-separated fields that must exist in each returned item. Fields must belong to the endpoint entity; invalid fields return 400 Bad Request.

Response fields

Field	Type	Description
`total`	`int`	Total number of languages found.
`rows.key`	`string`	Language code.
`rows.doc_count`	`int`	Number of posts for the language.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/posts/languages?filters=brandId:1&size=50' \
2  --header 'Authorization: Bearer YOUR_API_TOKEN'

GET/posts/histogramBearer required

7.7.Get post histogram

Return time-bucketed post counts or counter values 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.

Query parameters

Field	Type	Description
`size`	`int`	Maximum number of results to return.Default: `20 or endpoint-specific`
`page`	`int`	Zero-based page number.Default: `0`
`q`	`string`	Full-text search query.
`qf`	`string`	Comma-separated fields used by the full-text query.
`sort`	`string`	Sort expression. Prefix a field with "-" for descending order. Counter-backed endpoints can sort by counters.total.<field> or by the counter shorthand itself, for example sort=-engagement on post/social data or sort=-click on organic data.
`filters`	`string`	AND filters on item fields. Use semicolons between filters and ".." for ranges. Send the separators ":", ";", "," and ".." as raw characters: search endpoints read the raw query string and treat percent-encoded separators as literal value characters. Percent-encode only characters inside values, such as spaces (%20). On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203". On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`excludes`	`string`	Exclude results when a field contains a value. On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`fields`	`string`	Comma-separated fields to include in each returned item.
`exists`	`string`	Comma-separated fields that must exist in each returned item. Fields must belong to the endpoint entity; invalid fields return 400 Bad Request.
`histogramField`	`string`	Field used as the histogram date source.
`histogramInterval`	`string`	Bucket interval such as hour, day, week, or month.
`histogramTimezone`	`string`	Timezone offset used to build buckets.

Response fields

Field	Type	Description
`buckets`	`object[]`	Histogram buckets.
`buckets.key`	`string`	Bucket key or date.
`buckets.doc_count`	`int`	Number of posts in the bucket.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/posts/histogram?filters=brandId:1;publishedAt:2026-05-01T00:00:00Z..2026-05-27T23:59:59Z&histogramField=publishedAt&histogramInterval=day' \
2  --header 'Authorization: Bearer YOUR_API_TOKEN'

GET/posts/aggregationBearer required

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.

Query parameters

Field	Type	Description
`size`	`int`	Maximum number of results to return.Default: `20 or endpoint-specific`
`q`	`string`	Full-text search query.
`qf`	`string`	Comma-separated fields used by the full-text query.
`filters`	`string`	AND filters on item fields. Use semicolons between filters and ".." for ranges. Send the separators ":", ";", "," and ".." as raw characters: search endpoints read the raw query string and treat percent-encoded separators as literal value characters. Percent-encode only characters inside values, such as spaces (%20). On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203". On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`excludes`	`string`	Exclude results when a field contains a value. On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`exists`	`string`	Comma-separated fields that must exist in each returned item. Fields must belong to the endpoint entity; invalid fields return 400 Bad Request.
`field`	`string`	Field to aggregate.

Response fields

Field	Type	Description
`total`	`int`	Total number of aggregation buckets.
`rows.key`	`string`	Bucket key.
`rows.doc_count`	`int`	Bucket count.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/posts/aggregation?field=socialAccount.type&filters=brandId:1&size=20' \
2  --header 'Authorization: Bearer YOUR_API_TOKEN'

GET/posts/statsBearer required

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.

Query parameters

Field	Type	Description
`size`	`int`	Maximum number of results to return.Default: `20 or endpoint-specific`
`page`	`int`	Zero-based page number.Default: `0`
`q`	`string`	Full-text search query.
`qf`	`string`	Comma-separated fields used by the full-text query.
`sort`	`string`	Sort expression. Prefix a field with "-" for descending order. Counter-backed endpoints can sort by counters.total.<field> or by the counter shorthand itself, for example sort=-engagement on post/social data or sort=-click on organic data.
`filters`	`string`	AND filters on item fields. Use semicolons between filters and ".." for ranges. Send the separators ":", ";", "," and ".." as raw characters: search endpoints read the raw query string and treat percent-encoded separators as literal value characters. Percent-encode only characters inside values, such as spaces (%20). On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203". On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`excludes`	`string`	Exclude results when a field contains a value. On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`fields`	`string`	Comma-separated fields to include in each returned item.
`exists`	`string`	Comma-separated fields that must exist in each returned item. Fields must belong to the endpoint entity; invalid fields return 400 Bad Request.

Response fields

Field	Type	Description
`rows`	`object[]`	Stat rows returned by the selected filters.
`total`	`int`	Total matching posts or stats rows.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/posts/stats?filters=brandId:1;publishedAt:-30%20days..now&fields=counters.total&size=50' \
2  --header 'Authorization: Bearer YOUR_API_TOKEN'

POST/posts/checkBearer required

7.10.Check post content

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

Body parameters

Field	Type	Description
`message`	`string`	Post message to validate.
`title`	`string`	Post title.
`description`	`string`	Post description.
`socialAccount.type`	`string`	Target social network type.
`brandId`	`int`	Brand ID.

Response fields

Field	Type	Description
`valid`	`bool`	Whether the post content passed validation.
`warnings`	`object[]`	Warnings returned by publication checks.
`errors`	`object[]`	Blocking validation errors.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/posts/check' \
2  --header 'Content-Type: application/json' \
3  --header 'Authorization: Bearer YOUR_API_TOKEN' \
4  --data '{
5    "brandId": 1,
6    "message": "Post copy",
7    "socialAccount.type": "linkedin"
8  }'

GET/posts/tagsBearer required

7.11.Get post tags

Return matching tags 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.

Rate limit200 calls

Query parameters

Field	Type	Description
`size`	`int`	Count of results to return.Default: `10`
`prefix`	`string`	Tag prefix.
`selected`	`string`	Already selected tags, comma separated.
`q`	`string`	Full-text search query.
`qf`	`string`	Comma-separated fields used by the full-text query.
`filters`	`string`	AND filters on item fields. Use semicolons between filters and ".." for ranges. Send the separators ":", ";", "," and ".." as raw characters: search endpoints read the raw query string and treat percent-encoded separators as literal value characters. Percent-encode only characters inside values, such as spaces (%20). On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203". On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`excludes`	`string`	Exclude results when a field contains a value. On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`exists`	`string`	Comma-separated fields that must exist in each returned item. Fields must belong to the endpoint entity; invalid fields return 400 Bad Request.

Response fields

Field	Type	Description
`total`	`int`	Total number of items found.
`rows.key`	`string`	Tag.
`rows.doc_count`	`int`	Number of posts where the tag was found.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/posts/tags?filters=publishedAt:-30%20days..now;socialAccount.type:facebook&size=100' \
2  --header 'Authorization: Bearer YOUR_API_TOKEN'

GET/posts/topicsBearer required

7.12.Get post topics

Return matching topics 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.

Rate limit200 calls

Query parameters

Field	Type	Description
`size`	`int`	Count of results to return.Default: `10`
`prefix`	`string`	Topic prefix.
`selected`	`string`	Already selected topics, comma separated.
`q`	`string`	Full-text search query.
`qf`	`string`	Comma-separated fields used by the full-text query.
`filters`	`string`	AND filters on item fields. Use semicolons between filters and ".." for ranges. Send the separators ":", ";", "," and ".." as raw characters: search endpoints read the raw query string and treat percent-encoded separators as literal value characters. Percent-encode only characters inside values, such as spaces (%20). On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203". On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`excludes`	`string`	Exclude results when a field contains a value. On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`exists`	`string`	Comma-separated fields that must exist in each returned item. Fields must belong to the endpoint entity; invalid fields return 400 Bad Request.

Response fields

Field	Type	Description
`total`	`int`	Total number of items found.
`rows.key`	`string`	Topic.
`rows.doc_count`	`int`	Number of posts where the topic was found.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/posts/topics?filters=publishedAt:-30%20days..now;socialAccount.type:facebook&size=100' \
2  --header 'Authorization: Bearer YOUR_API_TOKEN'

POST/posts/bulkBearer required

7.13.Create posts in bulk

Create a collection of posts. Use postType "flying" with a shortlink mappingId to publish a flying link.

Rate limit200 calls

Body parameters

Field	Type	Description
`post`*	`Post[]`	Array of post objects.
->`brandId`*	`int`	Brand ID used to create the post.
->`postType`*	`string`	Nonli post type: text, video, link, photo, album, flying, reel, document, etc.
->`shortlink.mappingId`	`string`	Related shortlink ID.
->`message`	`string`	Post message.
->`title`	`string`	Displayed post title.
->`description`	`string`	Link or media description.
->`schedule.startDate`	`date`	Scheduled publication start date. If schedule is omitted, the post is published now.
->`image[].fontanSlug`	`string`	Fontan image slug.
->`image[].url`	`string`	External image URL.
->`video[].mappingId`	`string`	Uploaded video ID.

Response fields

Field	Type	Description
`Post[]`	`Post[]`	Created posts with status and additional values.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/posts/bulk' \
2  --header 'Content-Type: application/json' \
3  --header 'Authorization: Bearer YOUR_API_TOKEN' \
4  --data '{
5    "post": [
6      {
7        "brandId": 1,
8        "shortlink": {
9          "mappingId": "c9d00b2d-06bf-7aa6-aa33-50690e55xxxx"
10        },
11        "postType": "flying"
12      }
13    ]
14  }'

PUT/posts/bulkBearer required

7.14.Update posts in bulk

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

Rate limit200 calls

Body parameters

Field	Type	Description
`checkBeforeUpdate`	`bool`	Check posts before updating them and skip update if checks fail.
`updatePostOnNetwork`	`bool`	Update posts on the social network. Set false to update Nonli only.Default: `true`
`post`*	`Post[]`	Array of post objects to update.
->`id`*	`string`	Post ID.
->`createdAt`	`date`	Creation date, used to optimize the update request.
->`shortId`	`string`	New short ID.
->`schedule`	`object`	Scheduling information. Empty object publishes now.
->`message`	`string`	Updated post message.

Response fields

Field	Type	Description
`Post[]`	`Post[]`	Updated posts with status and additional values.

Example

bash

1curl --location --request PUT 'https://api.nonli.com/v2.1/posts/bulk' \
2  --header 'Content-Type: application/json' \
3  --header 'Authorization: Bearer YOUR_API_TOKEN' \
4  --data '{
5    "post": [
6      {
7        "id": "4283ab2d-e3dd-7b1a-7cd6-bbcc71e1xxxx",
8        "shortId": "new-short-id",
9        "schedule": {}
10      }
11    ]
12  }'

DELETE/posts/bulkBearer required

7.15.Delete posts in bulk

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

Rate limit100 calls

Body parameters

Field	Type	Description
`post`*	`Post[]`	Array of posts to delete.
->`id`*	`string`	Post ID to delete.
->`socialAccountExternalId`	`string`	External social account ID.
->`createdAt`	`date`	Creation date of the post to delete.
`async`	`bool`	Delete posts asynchronously.Default: `false`

Response fields

Field	Type	Description
`Post[]`	`Post[]`	Deleted posts or per-item errors.

Example

bash

1curl --location --request DELETE 'https://api.nonli.com/v2.1/posts/bulk' \
2  --header 'Content-Type: application/json' \
3  --header 'Authorization: Bearer YOUR_API_TOKEN' \
4  --data '{
5    "post": [
6      {
7        "id": "4283ab2d-e3dd-7b1a-7cd6-bbcc71e1xxxx",
8        "createdAt": "2024-11-26T10:07:36Z"
9      }
10    ]
11  }'

8.Shortlinks

9 endpoints

Create and search shortened URLs used by Nonli posts and attribution workflows.

GET/shortlinksBearer required

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.

Rate limit720 calls every 12 hours for API users

Query parameters

Field	Type	Description
`size`	`int`	Count of results to return.Default: `10`
`excludeFields`	`string`	Comma-separated fields to exclude from each item.Default: `counters`
`page`	`int`	Zero-based page number.Default: `0`
`q`	`string`	Full-text search query.
`qf`	`string`	Comma-separated fields used by the full-text query.
`sort`	`string`	Sort expression. Prefix a field with "-" for descending order. Counter-backed endpoints can sort by counters.total.<field> or by the counter shorthand itself, for example sort=-engagement on post/social data or sort=-click on organic data.
`filters`	`string`	AND filters on item fields. Use semicolons between filters and ".." for ranges. Send the separators ":", ";", "," and ".." as raw characters: search endpoints read the raw query string and treat percent-encoded separators as literal value characters. Percent-encode only characters inside values, such as spaces (%20). On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203". On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`excludes`	`string`	Exclude results when a field contains a value. On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`fields`	`string`	Comma-separated fields to include in each returned item.
`exists`	`string`	Comma-separated fields that must exist in each returned item. Fields must belong to the endpoint entity; invalid fields return 400 Bad Request.

Response fields

Field	Type	Description
`total`	`int`	Total number of items found.
`rows`	`Shortlink[]`	Shortlinks found on the requested page.
->`id`	`string`	Shortlink identifier.
->`createdAt`	`date`	Creation date.
->`targetUrl`	`string`	Target URL.
->`canonicalUrl`	`string`	Canonical URL.
->`title`	`string`	Title.
->`author`	`string`	Author.
->`counters.total`	`CounterTotal[]`	Aggregated counters.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/shortlinks?filters=counters.total.field:click&size=20&page=0&fields=id,title,createdAt,brandId,author,targetUrl,publishedOn,language,counters.total,counters.updatedAt,counters.graph,shortPostUrn&qf=title&sort=-createdAt' \
2  --header 'Authorization: Bearer YOUR_API_TOKEN'

GET/shortlinks/:shortlinkIdBearer required

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.

Query parameters

Field	Type	Description
`fields`	`string`	Comma-separated fields to include.
`filters`	`string`	Optional filters, for example counters.graph.counter.

Response fields

Field	Type	Description
`id`	`string`	Shortlink identifier.
`createdAt`	`date`	Creation date.
`targetUrl`	`string`	Target URL.
`canonicalUrl`	`string`	Canonical URL.
`title`	`string`	Title.
`counters.total`	`CounterTotal[]`	Aggregated counters.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/shortlinks/c9d00b2d-06bf-7aa6-aa33-50690e55xxxx?fields=id,title,targetUrl,counters.total' \
2  --header 'Authorization: Bearer YOUR_API_TOKEN'

GET/shortlinks/statsBearer required

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.

Query parameters

Field	Type	Description
`size`	`int`	Maximum number of results to return.Default: `20 or endpoint-specific`
`page`	`int`	Zero-based page number.Default: `0`
`q`	`string`	Full-text search query.
`qf`	`string`	Comma-separated fields used by the full-text query.
`sort`	`string`	Sort expression. Prefix a field with "-" for descending order. Counter-backed endpoints can sort by counters.total.<field> or by the counter shorthand itself, for example sort=-engagement on post/social data or sort=-click on organic data.
`filters`	`string`	AND filters on item fields. Use semicolons between filters and ".." for ranges. Send the separators ":", ";", "," and ".." as raw characters: search endpoints read the raw query string and treat percent-encoded separators as literal value characters. Percent-encode only characters inside values, such as spaces (%20). On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203". On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`excludes`	`string`	Exclude results when a field contains a value. On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`fields`	`string`	Comma-separated fields to include in each returned item.
`exists`	`string`	Comma-separated fields that must exist in each returned item. Fields must belong to the endpoint entity; invalid fields return 400 Bad Request.

Response fields

Field	Type	Description
`rows`	`object[]`	Shortlink stat rows.
`total`	`int`	Total number of matching stat rows.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/shortlinks/stats?filters=brandId:1;createdAt:-30%20days..now&fields=counters.total' \
2  --header 'Authorization: Bearer YOUR_API_TOKEN'

GET/shortlinks/authorsBearer required

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.

Query parameters

Field	Type	Description
`size`	`int`	Maximum number of results to return.Default: `20 or endpoint-specific`
`q`	`string`	Full-text search query.
`qf`	`string`	Comma-separated fields used by the full-text query.
`filters`	`string`	AND filters on item fields. Use semicolons between filters and ".." for ranges. Send the separators ":", ";", "," and ".." as raw characters: search endpoints read the raw query string and treat percent-encoded separators as literal value characters. Percent-encode only characters inside values, such as spaces (%20). On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203". On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`excludes`	`string`	Exclude results when a field contains a value. On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`exists`	`string`	Comma-separated fields that must exist in each returned item. Fields must belong to the endpoint entity; invalid fields return 400 Bad Request.

Response fields

Field	Type	Description
`total`	`int`	Total number of authors found.
`rows.key`	`string`	Author name or identifier.
`rows.doc_count`	`int`	Number of shortlinks for the author.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/shortlinks/authors?filters=brandId:1&size=100' \
2  --header 'Authorization: Bearer YOUR_API_TOKEN'

GET/shortlinks/brandsBearer required

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.

Query parameters

Field	Type	Description
`size`	`int`	Maximum number of results to return.Default: `20 or endpoint-specific`
`q`	`string`	Full-text search query.
`qf`	`string`	Comma-separated fields used by the full-text query.
`filters`	`string`	AND filters on item fields. Use semicolons between filters and ".." for ranges. Send the separators ":", ";", "," and ".." as raw characters: search endpoints read the raw query string and treat percent-encoded separators as literal value characters. Percent-encode only characters inside values, such as spaces (%20). On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203". On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`excludes`	`string`	Exclude results when a field contains a value. On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`exists`	`string`	Comma-separated fields that must exist in each returned item. Fields must belong to the endpoint entity; invalid fields return 400 Bad Request.

Response fields

Field	Type	Description
`total`	`int`	Total number of brands found.
`rows.key`	`string`	Brand identifier or name.
`rows.doc_count`	`int`	Number of shortlinks for the brand.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/shortlinks/brands?filters=createdAt:-30%20days..now&size=100' \
2  --header 'Authorization: Bearer YOUR_API_TOKEN'

POST/shortlinksBearer required

8.6.Create a shortlink

Create or extract a shortlink for a target URL.

Rate limit200 calls

Query parameters

Field	Type	Description
`fields`	`string`	Comma-separated fields to include in the response.

Body parameters

Field	Type	Description
`targetUrl`*	`string`	The target URL to shorten.
`brandId`	`int`	Brand ID to associate with the shortlink. If missing, the first company brand is used.
`maxImages`	`int`	Maximum images to retrieve while scraping.Default: `1`
`needOrganicIndexation`	`bool`	Index data as organic.
`forceCanonical`	`bool`	Force canonical URL handling.

Response fields

Field	Type	Description
`id`	`string`	Shortlink identifier.
`createdAt`	`date`	Creation date.
`canonicalUrl`	`string`	Canonical URL.
`targetUrl`	`string`	Target URL.
`title`	`string`	Title.
`fontanSlug`	`string[]`	Shortlink images.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/shortlinks?fields=id,title,createdAt,brandId,author,targetUrl,fontanSlug' \
2  --header 'Content-Type: application/json' \
3  --header 'Authorization: Bearer YOUR_API_TOKEN' \
4  --data '{
5    "targetUrl": "https://www.domain.com/my-article"
6  }'

Response example

json

1{
2  "id": "c9d00b2d-06bf-7aa6-aa33-50690e55xxx",
3  "title": "My shortlink title",
4  "targetUrl": "https://www.domain.com/my-article",
5  "canonicalUrl": "https://www.domain.com/my-article",
6  "createdAt": "2024-11-29T12:49:24.611Z",
7  "author": "API user",
8  "brandId": 1,
9  "fontanSlug": [
10    "media/www.domain.com/5bd63c819cd7ea3b919e281bc8e69487.jpg"
11  ]
12}

POST/shortlinks/bulkBearer required

8.7.Create shortlinks in bulk

Create several shortlinks in one request.

Rate limit200 calls

Body parameters

Field	Type	Description
`shortlink`*	`Shortlink[]`	Array of shortlink objects.
->`targetUrl`*	`string`	Target URL to shorten.
->`brandId`	`int`	Brand ID to associate.
->`title`	`string`	Optional title override.

Response fields

Field	Type	Description
`Shortlink[]`	`Shortlink[]`	Created shortlinks with IDs and metadata.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/shortlinks/bulk' \
2  --header 'Content-Type: application/json' \
3  --header 'Authorization: Bearer YOUR_API_TOKEN' \
4  --data '{
5    "shortlink": [
6      {
7        "targetUrl": "https://www.domain.com/article-1",
8        "brandId": 1
9      },
10      {
11        "targetUrl": "https://www.domain.com/article-2",
12        "brandId": 1
13      }
14    ]
15  }'

PUT/shortlinks/:shortlinkIdBearer required

8.8.Update a shortlink

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

Rate limit200 calls

Query parameters

Field	Type	Description
`fields`	`string`	Comma-separated fields to include in the response.

Body parameters

Field	Type	Description
`targetUrl`	`string`	New target URL.
`createdAt`	`string`	Creation date used to optimize lookup.
`brandId`	`int`	Brand ID to associate with the shortlink.
`title`	`string`	Title.
`description`	`string`	Description.
`scrape`	`bool`	Scrape the target.Default: `true`
`fontanSlug`	`string[]`	Shortlink images.

Response fields

Field	Type	Description
`id`	`string`	Shortlink identifier.
`targetUrl`	`string`	Target URL.
`canonicalUrl`	`string`	Canonical URL.
`title`	`string`	Title.
`description`	`string`	Description.
`fontanSlug`	`string[]`	Shortlink images.

Example

bash

1curl --location --request PUT 'https://api.nonli.com/v2.1/shortlinks/c9d00b2d-06bf-7aa6-aa33-50690e55xxxx' \
2  --header 'Content-Type: application/json' \
3  --header 'Authorization: Bearer YOUR_API_TOKEN' \
4  --data '{
5    "title": "Updated title",
6    "scrape": false
7  }'

POST/shortlinks/:shortlinkId/generate-messageBearer required

8.9.Generate a message for a shortlink

Generate suggested social copy for a shortlink and content type.

Body parameters

Field	Type	Description
`contentType`*	`string`	Target content type or network context.
`language`	`string`	Language code for the generated message.
`tone`	`string`	Optional tone or editorial instruction.

Response fields

Field	Type	Description
`message`	`string`	Generated message.
`alternatives`	`string[]`	Alternative generated messages when available.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/shortlinks/c9d00b2d-06bf-7aa6-aa33-50690e55xxxx/generate-message' \
2  --header 'Content-Type: application/json' \
3  --header 'Authorization: Bearer YOUR_API_TOKEN' \
4  --data '{
5    "contentType": "linkedin",
6    "language": "fr"
7  }'

9.Themes

6 endpoints

Read saved theme filters used by listening, publishing, and automation workflows.

GET/themesBearer required

9.1.Search themes

Return team, bot, or public themes visible to the API token role.

Rate limit720 calls every 12 hours for API users

Query parameters

Field	Type	Description
`size`	`int`	Count of results to return.Default: `1000`
`page`	`int`	Zero-based page number.Default: `0`
`sort`	`string`	Sort expression.
`fields`	`string`	Comma-separated fields to include.
`filters`	`string`	AND filters on item fields.
`filtersOr`	`string`	OR filters on item fields.
`scopes`	`string`	Theme visibility for API tokens: team, bot, public. Private themes are user-scoped and are not returned for Bearer API tokens.Default: `team`
`types`	`string`	Theme types. Defaults to listening.
`embed`	`string`	Use embed=roles to include associated roles.

Response fields

Field	Type	Description
`total`	`int`	Total number of items found.
`rows.id`	`int`	Unique theme ID.
`rows.name`	`string`	Name.
`rows.value`	`string`	Theme filters object.
`rows.scope`	`string`	Visibility scope.
`rows.roles`	`AclRoles[]`	Associated roles when embedded.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/themes?filters=lang:fr&fields=id,name,value,selected,scope,default,userId,companyId,lang,readonly&embed=roles&sort=name&scopes=team,bot,public' \
2  --header 'Authorization: Bearer YOUR_API_TOKEN'

GET/themes/:themeIdBearer required

9.2.Get a theme

Return one saved theme by ID.

Query parameters

Field	Type	Description
`fields`	`string`	Comma-separated fields to include.
`embed`	`string`	Use embed=roles to include associated roles.

Response fields

Field	Type	Description
`id`	`int`	Unique theme ID.
`name`	`string`	Name.
`value`	`string`	Theme filters object.
`queryStrings`	`object`	Prebuilt query strings for matching sections.
`scope`	`string`	Visibility scope.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/themes/123?fields=id,name,value,queryStrings,scope&embed=roles' \
2  --header 'Authorization: Bearer YOUR_API_TOKEN'

POST/themesBearer required

9.3.Create a theme

Create a saved theme from listening or post filters.

Body parameters

Field	Type	Description
`name`*	`string`	Theme name.
`type`*	`string`	Theme type, for example listening or post.
`scope`	`string`	Visibility scope for API tokens: team, bot, or public.
`lang`	`string`	Language code.
`value`*	`object`	Theme filters and section configuration.

Response fields

Field	Type	Description
`id`	`int`	Created theme ID.
`name`	`string`	Theme name.
`queryStrings`	`object`	Prebuilt query strings.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/themes' \
2  --header 'Content-Type: application/json' \
3  --header 'Authorization: Bearer YOUR_API_TOKEN' \
4  --data '{
5    "name": "Editorial performance",
6    "type": "listening",
7    "scope": "team",
8    "lang": "fr",
9    "value": {
10      "filters": {
11        "brandId": [1]
12      }
13    }
14  }'

PUT/themes/:themeIdBearer required

9.4.Update a theme

Update a saved theme and rebuild its query strings when the value changes.

Body parameters

Field	Type	Description
`name`	`string`	Theme name.
`scope`	`string`	Visibility scope.
`value`	`object`	Theme filters and section configuration.

Response fields

Field	Type	Description
`id`	`int`	Updated theme ID.
`name`	`string`	Theme name.
`queryStrings`	`object`	Prebuilt query strings.

Example

bash

1curl --location --request PUT 'https://api.nonli.com/v2.1/themes/123' \
2  --header 'Content-Type: application/json' \
3  --header 'Authorization: Bearer YOUR_API_TOKEN' \
4  --data '{
5    "name": "Updated theme"
6  }'

DELETE/themes/:themeIdBearer required

9.5.Delete a theme

Delete a saved theme.

Response fields

Field	Type	Description
`deleted`	`bool`	Whether the theme was deleted.

Example

bash

1curl --location --request DELETE 'https://api.nonli.com/v2.1/themes/123' \
2  --header 'Authorization: Bearer YOUR_API_TOKEN'

GET/themes/rolesBearer required

9.6.Get theme roles

Return roles that can be associated with team-scoped themes.

Response fields

Field	Type	Description
`total`	`int`	Total number of roles found.
`rows`	`AclRoles[]`	Available roles.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/themes/roles' \
2  --header 'Authorization: Bearer YOUR_API_TOKEN'

10.Listening

6 endpoints

Search social-network performance and organic website content signals.

GET/listening/socialBearer required

10.1.Get social listening

Search social posts and counters collected from supported social networks.

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.

Rate limit720 calls every 12 hours for API users

Query parameters

Field	Type	Description
`size`	`int`	Count of results to return.Default: `50`
`page`	`int`	Zero-based page number.Default: `0`
`q`	`string`	Full-text search query.
`qf`	`string`	Comma-separated fields used by the full-text query.
`sort`	`string`	Sort expression. Prefix a field with "-" for descending order. Counter-backed endpoints can sort by counters.total.<field> or by the counter shorthand itself, for example sort=-engagement on post/social data or sort=-click on organic data.
`filters`	`string`	AND filters on item fields. Use semicolons between filters and ".." for ranges. Send the separators ":", ";", "," and ".." as raw characters: search endpoints read the raw query string and treat percent-encoded separators as literal value characters. Percent-encode only characters inside values, such as spaces (%20). On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203". On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`excludes`	`string`	Exclude results when a field contains a value. On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`fields`	`string`	Comma-separated fields to include in each returned item.
`exists`	`string`	Comma-separated fields that must exist in each returned item. Fields must belong to the endpoint entity; invalid fields return 400 Bad Request.

Response fields

Field	Type	Description
`total`	`int`	Total number of items found.
`rows`	`Post[]`	Social listening posts found on the requested page.
`rows.socialAccount.type`	`string`	Social network: facebook, linkedin, instagram, etc.
`rows.counters.total.field`	`string`	Counter metric name.
`rows.counters.total.value`	`int`	Counter total value.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/listening/social?filters=publishedAt:-15%20minutes..now;socialAccount.type:facebook&filtersOr=counters.graph.counter:engagement&size=5&fields=id,publishedAt,message,title,description,image,postType,language,video,targetUrl,socialAccount,counters.total,counters.updatedAt,counters.graph,shortDomain,shortId,shortlink&qf=title,message,description,category&sort=-engagement' \
2  --header 'Authorization: Bearer YOUR_API_TOKEN'

GET/listening/organicBearer required

10.2.Get organic listening

Search website content indexed by Organic Listening.

Organic Listening endpoints accept standard Organic Listening counters only. Post counters such as engagement, reach, or videoViews are invalid for Organic Listening and return 400 Bad Request.

Rate limit720 calls every 12 hours for API users

Query parameters

Field	Type	Description
`size`	`int`	Count of results to return.Default: `10`
`page`	`int`	Zero-based page number.Default: `0`
`q`	`string`	Full-text search query.
`qf`	`string`	Comma-separated fields used by the full-text query.
`sort`	`string`	Sort expression. Prefix a field with "-" for descending order. Counter-backed endpoints can sort by counters.total.<field> or by the counter shorthand itself, for example sort=-engagement on post/social data or sort=-click on organic data.
`filters`	`string`	AND filters on item fields. Use semicolons between filters and ".." for ranges. Send the separators ":", ";", "," and ".." as raw characters: search endpoints read the raw query string and treat percent-encoded separators as literal value characters. Percent-encode only characters inside values, such as spaces (%20). On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203". On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`excludes`	`string`	Exclude results when a field contains a value. On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`fields`	`string`	Comma-separated fields to include in each returned item.
`exists`	`string`	Comma-separated fields that must exist in each returned item. Fields must belong to the endpoint entity; invalid fields return 400 Bad Request.
`excludeFields`	`string`	Comma-separated fields not to return.
`histogramDateTimeRange`	`string`	Histogram date-time range for sort aggregation.

Response fields

Field	Type	Description
`total`	`int`	Total number of items found.
`rows`	`Organic[]`	Organic content found on the requested page.
`rows.canonicalUrl`	`string`	Canonical URL.
`rows.title`	`string`	Title.
`rows.type`	`string`	Content type: article, product, website, etc.
`rows.counters.total.field`	`string`	Organic counter field.
`rows.counters.total.value`	`int`	Counter total value.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/listening/organic?filters=type:article&filtersOr=counters.graph.counter:click&sort=-click&size=10&fields=title,description,canonicalUrl,publishedAt,counters.total&histogramDateTimeRange=global' \
2  --header 'Authorization: Bearer YOUR_API_TOKEN'

GET/listening/organic/:organicIdBearer required

10.3.Get organic content

Return one indexed organic content item by ID.

Query parameters

Field	Type	Description
`fields`	`string`	Comma-separated fields to include.

Response fields

Field	Type	Description
`id`	`string`	Organic content ID.
`canonicalUrl`	`string`	Canonical URL.
`title`	`string`	Title.
`description`	`string`	Description.
`publishedAt`	`date`	Publication date.
`counters.total`	`CounterTotal[]`	Aggregated counters.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/listening/organic/8f14e45fceea167a5a36dedd4bea2543?fields=id,title,canonicalUrl,counters.total' \
2  --header 'Authorization: Bearer YOUR_API_TOKEN'

GET/listening/organic/statsBearer required

10.4.Get organic stats

Return aggregated Organic Listening performance statistics.

Organic Listening endpoints accept standard Organic Listening counters only. Post counters such as engagement, reach, or videoViews are invalid for Organic Listening and return 400 Bad Request.

Query parameters

Field	Type	Description
`size`	`int`	Maximum number of results to return.Default: `20 or endpoint-specific`
`page`	`int`	Zero-based page number.Default: `0`
`q`	`string`	Full-text search query.
`qf`	`string`	Comma-separated fields used by the full-text query.
`sort`	`string`	Sort expression. Prefix a field with "-" for descending order. Counter-backed endpoints can sort by counters.total.<field> or by the counter shorthand itself, for example sort=-engagement on post/social data or sort=-click on organic data.
`filters`	`string`	AND filters on item fields. Use semicolons between filters and ".." for ranges. Send the separators ":", ";", "," and ".." as raw characters: search endpoints read the raw query string and treat percent-encoded separators as literal value characters. Percent-encode only characters inside values, such as spaces (%20). On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203". On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`excludes`	`string`	Exclude results when a field contains a value. On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`fields`	`string`	Comma-separated fields to include in each returned item.
`exists`	`string`	Comma-separated fields that must exist in each returned item. Fields must belong to the endpoint entity; invalid fields return 400 Bad Request.

Response fields

Field	Type	Description
`rows`	`object[]`	Stat rows returned by the selected filters.
`total`	`int`	Total matching content or stats rows.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/listening/organic/stats?filters=type:article;publishedAt:-30%20days..now&fields=counters.total' \
2  --header 'Authorization: Bearer YOUR_API_TOKEN'

GET/listening/organic/aggregationBearer required

10.5.Get organic aggregation

Return generic aggregations for Organic Listening dashboards and filters.

Organic Listening endpoints accept standard Organic Listening counters only. Post counters such as engagement, reach, or videoViews are invalid for Organic Listening and return 400 Bad Request.

Query parameters

Field	Type	Description
`size`	`int`	Maximum number of results to return.Default: `20 or endpoint-specific`
`q`	`string`	Full-text search query.
`qf`	`string`	Comma-separated fields used by the full-text query.
`filters`	`string`	AND filters on item fields. Use semicolons between filters and ".." for ranges. Send the separators ":", ";", "," and ".." as raw characters: search endpoints read the raw query string and treat percent-encoded separators as literal value characters. Percent-encode only characters inside values, such as spaces (%20). On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203". On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`excludes`	`string`	Exclude results when a field contains a value. On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`exists`	`string`	Comma-separated fields that must exist in each returned item. Fields must belong to the endpoint entity; invalid fields return 400 Bad Request.
`field`	`string`	Field to aggregate.

Response fields

Field	Type	Description
`total`	`int`	Total number of buckets.
`rows.key`	`string`	Bucket key.
`rows.doc_count`	`int`	Bucket count.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/listening/organic/aggregation?field=type&filters=publishedAt:-30%20days..now&size=20' \
2  --header 'Authorization: Bearer YOUR_API_TOKEN'

GET/listening/organic/suggest/:fieldBearer required

10.6.Suggest organic filter values

Return autocomplete suggestions for an Organic Listening field.

Query parameters

Field	Type	Description
`q`	`string`	Suggestion query.
`size`	`int`	Count of suggestions to return.Default: `10`
`filters`	`string`	Optional filters to constrain suggestions.

Response fields

Field	Type	Description
`rows`	`object[]`	Suggested field values.
`rows.key`	`string`	Suggested value.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/listening/organic/suggest/title?q=election&size=10' \
2  --header 'Authorization: Bearer YOUR_API_TOKEN'

11.Leaderboard

3 endpoints

Rank social accounts by an aggregated post counter over any post filter set. Rows combine ranking values with account profile data.

GET/posts/leaderboardBearer required

11.1.Get the leaderboard

Return social accounts ranked by an aggregated post counter, with per post type breakdowns and account profile data.

aggregationField and additionalAggregationFields accept the documented post counter names, such as engagement, reach, videoViews, click, ctr, overperforming, or monetization. The API resolves each documented name to the stored counter internally; historical internal counter names are intentionally undocumented.
Counters built from public network data, such as engagement or videoViews, rank any listened account. Counters that require account ownership automatically restrict the leaderboard to social accounts the API token can access.
Leaderboard filters and sorts accept the shorthand fields name, slug, category, and verificationStatus, resolved to the matching socialAccount fields internally.

Query parameters

Field	Type	Description
`aggregationField`*	`string`	Documented post counter used to rank accounts, for example engagement, reach, videoViews, click, ctr, overperforming, or monetization.
`additionalAggregationFields`	`string`	Comma-separated additional documented counters to aggregate per account. Each counter is returned on the row under the requested counter name.
`size`	`int`	Count of accounts to return, between 1 and 200.Default: `20`
`page`	`int`	Zero-based page number.Default: `0`
`q`	`string`	Full-text search query.
`qf`	`string`	Comma-separated fields used by the full-text query, for example title,message,description,category.
`sort`	`string`	Ranking direction. Use counters.total.<counter> with the documented counter name, for example sort=-counters.total.engagement. Defaults to descending on aggregationField.
`filters`	`string`	AND filters on post fields, such as publishedAt ranges or socialAccount.type. The shorthand fields name, slug, category, and verificationStatus filter the matching socialAccount fields.
`filtersOr`	`string`	OR filters on post fields.
`excludes`	`string`	Exclude results when a field contains a value.
`exists`	`string`	Comma-separated fields that must exist in matching posts.

Response fields

Field	Type	Description
`LeaderboardRow[]`	`LeaderboardRow[]`	Accounts ranked by the aggregated counter. The response is a JSON array without a total wrapper.
->`externalId`	`string`	Social network account/page ID.
->`name`	`string`	Account display name.
->`type`	`string`	Social network: facebook, instagram, linkedin, etc.
->`slug`	`string`	Account slug.
->`picture`	`string`	Account profile picture URL.
->`website`	`string`	Account website.
->`docCount`	`int`	Number of posts matching the filters for the account.
->`value`	`float`	Aggregated aggregationField value across matching posts.
->`percent`	`float`	Aggregated value relative to the account fan count.
->`types`	`object`	Per post type breakdown keyed by post type, each entry with type, docCount, value, and percent.
->`fanCount`	`int`	Account fan count.
->`followerCount`	`int`	Estimated follower count.
->`verificationStatus`	`string`	Network verification status.
->`createdAt`	`date`	Account creation date.
->`counters`	`CounterTotal[]`	Account counter totals.
->`<counter>`	`object`	One entry per additionalAggregationFields counter, keyed by the requested counter name, with value, docCount, and types.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/posts/leaderboard?aggregationField=engagement&additionalAggregationFields=videoViews&filters=publishedAt:-30%20days..now;socialAccount.type:facebook&size=10' \
2  --header 'Authorization: Bearer YOUR_API_TOKEN'

Response example

json

1[
2  {
3    "externalId": "339028534278",
4    "name": "Media page",
5    "type": "facebook",
6    "slug": "@mediapage",
7    "picture": "https://...",
8    "docCount": 1240,
9    "value": 458200,
10    "percent": 12.4,
11    "fanCount": 3690000,
12    "followerCount": 3720000,
13    "verificationStatus": "blue_verified",
14    "types": {
15      "link": { "type": "link", "docCount": 980, "value": 310500, "percent": 8.4 },
16      "video": { "type": "video", "docCount": 260, "value": 147700, "percent": 4.0 }
17    },
18    "videoViews": {
19      "externalId": "339028534278",
20      "docCount": 260,
21      "value": 985000,
22      "types": {
23        "video": { "type": "video", "docCount": 260, "value": 985000 }
24      }
25    }
26  }
27]

POST/posts/leaderboard/_searchBearer required

11.2.Search the leaderboard

Same ranking as GET /posts/leaderboard with parameters sent in the JSON body. Use it when the filter set exceeds URL length limits, for example large theme filters.

aggregationField and additionalAggregationFields accept the documented post counter names, such as engagement, reach, videoViews, click, ctr, overperforming, or monetization. The API resolves each documented name to the stored counter internally; historical internal counter names are intentionally undocumented.
Counters built from public network data, such as engagement or videoViews, rank any listened account. Counters that require account ownership automatically restrict the leaderboard to social accounts the API token can access.
Leaderboard filters and sorts accept the shorthand fields name, slug, category, and verificationStatus, resolved to the matching socialAccount fields internally.

Body parameters

Field	Type	Description
`aggregationField`*	`string`	Documented post counter used to rank accounts, for example engagement, reach, videoViews, click, ctr, overperforming, or monetization.
`additionalAggregationFields`	`string`	Comma-separated additional documented counters to aggregate per account.
`size`	`int`	Count of accounts to return, between 1 and 200.Default: `20`
`page`	`int`	Zero-based page number.Default: `0`
`q`	`string`	Full-text search query.
`qf`	`string`	Comma-separated fields used by the full-text query.
`sort`	`string`	Ranking direction, for example -counters.total.engagement.
`filters`	`string`	AND filters on post fields, using the same grammar as query string filters.
`filtersOr`	`string`	OR filters on post fields.
`excludes`	`string`	Exclude results when a field contains a value.
`exists`	`string`	Comma-separated fields that must exist in matching posts.

Response fields

Field	Type	Description
`LeaderboardRow[]`	`LeaderboardRow[]`	Same response as GET /posts/leaderboard.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/posts/leaderboard/_search' \
2  --header 'Content-Type: application/json' \
3  --header 'Authorization: Bearer YOUR_API_TOKEN' \
4  --data '{
5    "aggregationField": "videoViews",
6    "filters": "publishedAt:-30 days..now;socialAccount.type:facebook",
7    "qf": "title,message,description,category",
8    "size": 40
9  }'

GET/posts/leaderboard/categoriesBearer required

11.3.Get leaderboard categories

Return the per post type counter breakdown for selected leaderboard accounts.

aggregationField and additionalAggregationFields accept the documented post counter names, such as engagement, reach, videoViews, click, ctr, overperforming, or monetization. The API resolves each documented name to the stored counter internally; historical internal counter names are intentionally undocumented.

Query parameters

Field	Type	Description
`accountIds`*	`string`	Comma-separated external account IDs, from the externalId of leaderboard rows.
`aggregationField`*	`string`	Documented post counter to aggregate per post type.
`size`	`int`	Count of accounts to return, between 1 and 200.Default: `20`
`q`	`string`	Full-text search query.
`qf`	`string`	Comma-separated fields used by the full-text query.
`filters`	`string`	AND filters on post fields.
`filtersOr`	`string`	OR filters on post fields.
`excludes`	`string`	Exclude results when a field contains a value.
`exists`	`string`	Comma-separated fields that must exist in matching posts.

Response fields

Field	Type	Description
`LeaderboardCategoryRow[]`	`LeaderboardCategoryRow[]`	Per account post type breakdown. The response is a JSON array without a total wrapper.
->`externalId`	`string`	Social network account/page ID.
->`types`	`object`	Breakdown keyed by post type, each entry with value and docCount for the aggregated counter.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/posts/leaderboard/categories?accountIds=339028534278,224444370873&aggregationField=engagement&filters=publishedAt:-30%20days..now' \
2  --header 'Authorization: Bearer YOUR_API_TOKEN'

12.Accounts

5 endpoints

Search and manage the social accounts tracked by Social Listening, such as media pages and competitors. These are listening entities, distinct from the connected social accounts used for publishing.

GET/accountsBearer required

12.1.Search accounts

Search social accounts tracked by Social Listening, with profile data and account counters.

Accounts endpoints expose account counters only, currently follower_count (account fans or followers). The API resolves this documented name to the stored account counter internally, and responses echo the name the request used. Address it with the full counter path, for example sort=-counters.total.follower_count or filters=counters.graph.counter:follower_count. Post counters such as engagement or reach are invalid for Accounts.
The category filter and query field resolve to the localized account category internally; filter with category:<value> rather than a localized field path.

Query parameters

Field	Type	Description
`size`	`int`	Count of results to return.Default: `50`
`page`	`int`	Zero-based page number.Default: `0`
`sort`	`string`	Sort expression. Counter sorts use the full path, for example sort=-counters.total.follower_count.
`fields`	`string`	Comma-separated fields to include in each returned item.
`filters`	`string`	AND filters on account fields. Filter type:<network> to select a network and listeningActivated:true to restrict to accounts with listening enabled. Use counters.graph.counter:<counter> to return counter graphs.
`filtersOr`	`string`	OR filters on account fields.
`excludes`	`string`	Exclude results when a field contains a value.
`q`	`string`	Full-text search query.
`qf`	`string`	Comma-separated fields used by the full-text query.

Response fields

Field	Type	Description
`total`	`int`	Total number of items found.
`rows`	`Account[]`	Accounts found on the requested page.
->`id`	`string`	Account document ID, a hash string (listening accounts do not use integer IDs).
->`externalId`	`string`	Social network account/page ID.
->`name`	`string`	Account display name.
->`type`	`string`	Social network: facebook, instagram, linkedin, etc.
->`subType`	`string`	Account sub-type on the network, for example page or group.
->`slug`	`string`	Account slug.
->`url`	`string`	Account URL on the network.
->`picture`	`string`	Account profile picture URL.
->`website`	`string`	Account website.
->`about`	`string`	Account description.
->`category`	`object`	Localized account category.
->`place`	`object`	Localized location data with country, state, and city.
->`listeningActivated`	`bool`	Whether listening is enabled for the account.
->`verificationStatus`	`string`	Network verification status.
->`counters.total`	`CounterTotal[]`	Account counter totals.
->`counters.graph`	`object[]`	Counter graphs when requested with counters.graph.counter filters.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/accounts?filters=type:facebook;counters.graph.counter:follower_count&sort=-counters.total.follower_count&fields=id,externalId,name,slug,type,picture,verificationStatus,category,place,listeningActivated,about,counters.total,counters.graph&size=10' \
2  --header 'Authorization: Bearer YOUR_API_TOKEN'

POST/accountsBearer required

12.2.Add an account

Add a social account to Social Listening. The account is fetched from the network, activated for listening, and returned. Requires a role with the listening manage permission.

Body parameters

Field	Type	Description
`network`*	`string`	Social network of the account: facebook, instagram, linkedin, etc.
`accountId`	`string`	External account ID or slug on the network. Provide accountId or slug.
`slug`	`string`	Account slug on the network. Provide accountId or slug.
`instanceUrl`	`string`	Instance URL, required for federated networks such as Mastodon.

Response fields

Field	Type	Description
`Account`	`Account`	Created or updated account, with the same fields as search results.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/accounts' \
2  --header 'Content-Type: application/json' \
3  --header 'Authorization: Bearer YOUR_API_TOKEN' \
4  --data '{
5    "network": "facebook",
6    "slug": "mediapage"
7  }'

GET/accounts/categoriesBearer required

12.3.Get account categories

Return account category aggregations for autocomplete and listening filters.

The category filter and query field resolve to the localized account category internally; filter with category:<value> rather than a localized field path.

Rate limit200 calls

Query parameters

Field	Type	Description
`size`	`int`	Count of results to return.Default: `10`
`prefix`	`string`	Category prefix.
`selected`*	`string`	Already selected categories, comma separated. Send an empty value when no category is selected yet.
`q`	`string`	Full-text search query.
`qf`	`string`	Comma-separated fields used by the full-text query.
`filters`	`string`	AND filters on account fields.
`filtersOr`	`string`	OR filters on account fields.
`excludes`	`string`	Exclude results when a field contains a value.
`exists`	`string`	Comma-separated fields that must exist in each returned item.

Response fields

Field	Type	Description
`total`	`int`	Total number of categories found.
`rows.key`	`string`	Category value.
`rows.doc_count`	`int`	Number of accounts in the category.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/accounts/categories?prefix=News&selected=&filters=type:facebook&size=10' \
2  --header 'Authorization: Bearer YOUR_API_TOKEN'

GET/accounts/locationsBearer required

12.4.Search account locations

Return location accounts, such as city pages, matching a query. Local index results are combined with a remote network search. A type filter selecting the social network is required.

Query parameters

Field	Type	Description
`size`	`int`	Count of results to return.Default: `20`
`q`	`string`	Location search query.
`filters`*	`string`	AND filters. The type:<network> filter selecting the social network to search is required.

Response fields

Field	Type	Description
`total`	`int`	Total number of locations found.
`rows`	`Account[]`	Location accounts, including geoname data.
`q`	`string`	Echo of the search query.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/accounts/locations?q=Paris&filters=type:facebook&size=20' \
2  --header 'Authorization: Bearer YOUR_API_TOKEN'

GET/accounts/statsBearer required

12.5.Get account stats

Return aggregated account counter statistics with optional trend and histogram data.

Accounts endpoints expose account counters only, currently follower_count (account fans or followers). The API resolves this documented name to the stored account counter internally, and responses echo the name the request used. Address it with the full counter path, for example sort=-counters.total.follower_count or filters=counters.graph.counter:follower_count. Post counters such as engagement or reach are invalid for Accounts.

Query parameters

Field	Type	Description
`filters`	`string`	AND filters on account fields.
`filtersOr`	`string`	OR filters on account fields.
`excludes`	`string`	Exclude results when a field contains a value.
`exists`	`string`	Comma-separated fields that must exist in each item.
`q`	`string`	Full-text search query.
`qf`	`string`	Comma-separated fields used by the full-text query.
`metric`	`string`	Aggregation metric: sum, avg, med, or percentiles.
`dateTimeRange`	`string`	Date-time range used to calculate the trend.
`timezone`	`string`	Timezone used to resolve previous periods for the trend.
`percentile`	`float`	Queried percentile when metric is percentiles.
`granularity`	`string`	Histogram granularity: hour, day, week, month, or year. Auto-selected from the filtered period when omitted.

Response fields

Field	Type	Description
`total`	`object[]`	Aggregated counter totals.
`total.field`	`string`	Account counter field.
`total.value`	`float`	Aggregated value.
`total.trend`	`float`	Trend versus the previous period when dateTimeRange is provided.
`graph`	`object[]`	Counter histograms.
`graph.counter`	`string`	Account counter field.
`graph.histogram`	`object[]`	Time-bucketed counter values.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/accounts/stats?filters=type:facebook;listeningActivated:true;counters.graph.counter:follower_count&metric=sum&granularity=day' \
2  --header 'Authorization: Bearer YOUR_API_TOKEN'

13.Bots

6 endpoints

Manage automation bots that transform sources such as feeds, themes, or social accounts into publishable posts.

GET/botsBearer required

13.1.Search bots

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

Query parameters

Field	Type	Description
`size`	`int`	Count of results to return.Default: `20`
`page`	`int`	Zero-based page number.Default: `0`
`q`	`string`	Full-text search query.
`qf`	`string`	Comma-separated fields used by the full-text query.
`sort`	`string`	Sort expression. Prefix a field with "-" for descending order. Counter-backed endpoints can sort by counters.total.<field> or by the counter shorthand itself, for example sort=-engagement on post/social data or sort=-click on organic data.
`filters`	`string`	AND filters on item fields. Use semicolons between filters and ".." for ranges. Send the separators ":", ";", "," and ".." as raw characters: search endpoints read the raw query string and treat percent-encoded separators as literal value characters. Percent-encode only characters inside values, such as spaces (%20). On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203". On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`excludes`	`string`	Exclude results when a field contains a value. On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`fields`	`string`	Comma-separated fields to include in each returned item.
`exists`	`string`	Comma-separated fields that must exist in each returned item. Fields must belong to the endpoint entity; invalid fields return 400 Bad Request.
`embed`	`string`	Can embed running and spamControl.

Response fields

Field	Type	Description
`total`	`int`	Total number of bots found.
`rows`	`Bot[]`	Bots found on the requested page.
->`id`	`string`	Bot UUID.
->`title`	`string`	Bot title.
->`brandId`	`int`	Brand attached to the bot.
->`auto`	`bool`	Whether the bot publishes automatically.
->`activation`	`object`	Activation and scheduling state.
->`source`	`object`	Bot source configuration.
->`target`	`object[]`	Bot target configurations.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/bots?fields=id,title,brandId,auto,activation,source,target&embed=running&size=20' \
2  --header 'Authorization: Bearer YOUR_API_TOKEN'

GET/bots/:botIdBearer required

13.2.Get a bot

Return one bot by UUID.

Query parameters

Field	Type	Description
`fields`	`string`	Comma-separated fields to include.
`embed`	`string`	Can embed running and spamControl.

Response fields

Field	Type	Description
`id`	`string`	Bot UUID.
`title`	`string`	Bot title.
`brandId`	`int`	Brand attached to the bot.
`activation`	`object`	Activation and scheduling state.
`source`	`object`	Source configuration.
`target`	`object[]`	Target configurations.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/bots/5c9b6e52-8d4e-4f16-9f16-c01e9cbbd9e1?fields=id,title,brandId,activation,source,target&embed=running' \
2  --header 'Authorization: Bearer YOUR_API_TOKEN'

POST/bots/bulkBearer required

13.3.Create bots in bulk

Create one or more bots. Source and target URNs must reference resources visible to the API token role.

Bot trigger counters and post-rate metrics use the documented post counters. Percentile-based triggers resolve the documented counter name before calculating the percentile.

Body parameters

Field	Type	Description
`bot`*	`Bot[]`	Bots to create.
->`title`*	`string`	Bot title.
->`brandId`*	`int`	Brand attached to the bot.
->`auto`	`bool`	If false, created posts are kept for review before publishing.
->`activation`	`object`	Activation state and optional time window.
->`timezone`	`string`	Timezone used for activation windows.
->`runCyclePeriod`	`object`	Minimum and maximum minutes between source reads.
->`schedule`	`object`	Post scheduling options.
->`source`*	`object`	Source object with a Nonli URN.
->`target`*	`object[]`	Target objects with Nonli URNs.
->`post`	`object[]`	Post template configuration.
->`fieldMapping`	`object[]`	Source-to-target field mappings.
->`sourceMessage`	`string`	Source field used to build the post message.
->`sourceTitle`	`string`	Source field used to build the post title.
->`sourceImage`	`string`	Source field used to build the post image.
->`trigger.counter[].field`	`string`	Counter field that must reach trigger.counter[].triggerValue before the bot posts. Accepts documented post counter names such as engagement or reach for social-account sources.
->`trigger.counter[].triggerValue`	`int`	Counter threshold used by the trigger.
->`trigger.counter[].metric`	`string`	Optional aggregation metric used to calculate the trigger value, for example percentiles. The trigger counter field is resolved from the documented counter name before the aggregation is built.
->`postRate.mode`	`string`	Post type selection mode. Use manual for fixed post-type ratios, auto_all to auto-select from all post types, or auto_photo_link to auto-select between photo and link posts.
->`postRate.metric`	`string`	Performance metric used by automatic post type selection. Accepts documented post counter names such as engagement, reach, videoViews, and monetization.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/bots/bulk' \
2  --header 'Content-Type: application/json' \
3  --header 'Authorization: Bearer YOUR_API_TOKEN' \
4  --data '{
5    "bot": [
6      {
7        "title": "Morning feed review",
8        "brandId": 1,
9        "auto": false,
10        "activation": {
11          "alive": false
12        },
13        "timezone": "Europe/Paris",
14        "runCyclePeriod": {
15          "min": 30,
16          "max": 60
17        },
18        "source": {
19          "urn": "urn:nonli:feed:https://example.com/rss.xml",
20          "name": "Editorial feed"
21        },
22        "target": [
23          {
24            "urn": "urn:nonli:sa:facebook:PAGE_ID",
25            "name": "Facebook page"
26          }
27        ],
28        "post": [
29          {
30            "index": 0,
31            "prefix": "",
32            "suffix": ""
33          }
34        ],
35        "trigger": {
36          "counter": [
37            {
38              "field": "engagement",
39              "triggerValue": 75,
40              "metric": "percentiles"
41            }
42          ]
43        },
44        "postRate": {
45          "mode": "auto_all",
46          "metric": "engagement"
47        },
48        "fieldMapping": [
49          {
50            "source": "title",
51            "target": "message"
52          }
53        ],
54        "sourceMessage": "title",
55        "sourceTitle": "title",
56        "sourceImage": "og_image"
57      }
58    ]
59  }'

Response example

json

1[
2  {
3    "id": "5c9b6e52-8d4e-4f16-9f16-c01e9cbbd9e1",
4    "title": "Morning feed review",
5    "brandId": 1,
6    "activation": {
7      "alive": false
8    }
9  },
10  {
11    "error": "Bot creation failed"
12  }
13]

PUT/bots/bulkBearer required

13.4.Update bots in bulk

Update one or more bots. Each item must include the bot UUID and only the fields to change.

Bot trigger counters and post-rate metrics use the documented post counters. Percentile-based triggers resolve the documented counter name before calculating the percentile.

Body parameters

Field	Type	Description
`bot`*	`Bot[]`	Bots to update.
->`id`*	`string`	Bot UUID.
->`title`	`string`	Bot title.
->`brandId`	`int`	Brand attached to the bot.
->`auto`	`bool`	Whether the bot publishes automatically.
->`activation`	`object`	Activation state and optional time window.
->`runCyclePeriod`	`object`	Minimum and maximum minutes between source reads.
->`schedule`	`object`	Post scheduling options.
->`source`	`object`	Source object with a Nonli URN.
->`target`	`object[]`	Target objects with Nonli URNs.
->`post`	`object[]`	Post template configuration.
->`fieldMapping`	`object[]`	Source-to-target field mappings.
->`trigger.counter[].field`	`string`	Counter field that must reach trigger.counter[].triggerValue before the bot posts. Accepts documented post counter names such as engagement or reach for social-account sources.
->`trigger.counter[].triggerValue`	`int`	Counter threshold used by the trigger.
->`trigger.counter[].metric`	`string`	Optional aggregation metric used to calculate the trigger value, for example percentiles. The trigger counter field is resolved from the documented counter name before the aggregation is built.
->`postRate.mode`	`string`	Post type selection mode. Use manual for fixed post-type ratios, auto_all to auto-select from all post types, or auto_photo_link to auto-select between photo and link posts.
->`postRate.metric`	`string`	Performance metric used by automatic post type selection. Accepts documented post counter names such as engagement, reach, videoViews, and monetization.

Example

bash

1curl --location --request PUT 'https://api.nonli.com/v2.1/bots/bulk' \
2  --header 'Content-Type: application/json' \
3  --header 'Authorization: Bearer YOUR_API_TOKEN' \
4  --data '{
5    "bot": [
6      {
7        "id": "5c9b6e52-8d4e-4f16-9f16-c01e9cbbd9e1",
8        "title": "Morning feed review",
9        "activation": {
10          "alive": true
11        },
12        "runCyclePeriod": {
13          "min": 45,
14          "max": 90
15        }
16      }
17    ]
18  }'

Response example

json

1[
2  {
3    "id": "5c9b6e52-8d4e-4f16-9f16-c01e9cbbd9e1",
4    "title": "Morning feed review",
5    "brandId": 1,
6    "activation": {
7      "alive": true
8    }
9  },
10  {
11    "error": "Bot update failed"
12  }
13]

DELETE/bots/:botIdBearer required

13.5.Delete a bot

Delete one bot by UUID. A successful deletion returns HTTP 204 with no response body.

Example

bash

1curl --location --request DELETE 'https://api.nonli.com/v2.1/bots/5c9b6e52-8d4e-4f16-9f16-c01e9cbbd9e1' \
2  --header 'Authorization: Bearer YOUR_API_TOKEN'

GET/bots/infoBearer required

13.6.Get bot configuration info

Return schedule periods, target validation rules, and bot configuration constraints used to build valid bot payloads.

Query parameters

Field	Type	Description
`sourceUrn`	`string`	Optional source URN to evaluate source-specific configuration.
`targetUrn`	`string`	Optional target URN to evaluate target-specific configuration.

Response fields

Field	Type	Description
`schedulePeriods`	`object`	Available schedule period identifiers and labels.
`targetValidationConfigs`	`object`	Validation rules by target type.
`config`	`object`	Bot defaults and constraints, including AI generated text and consultation frequency.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/bots/info?sourceUrn=urn%3Anonli%3Afeed%3Ahttps%3A%2F%2Fexample.com%2Frss.xml&targetUrn=urn%3Anonli%3Asa%3Afacebook%3APAGE_ID' \
2  --header 'Authorization: Bearer YOUR_API_TOKEN'

14.Media

2 endpoints

Search reusable media and metadata used by the publishing composer.

GET/mediaBearer required

14.1.Search media

Return media items available to the current company and user.

Query parameters

Field	Type	Description
`size`	`int`	Count of results to return.Default: `50`
`page`	`int`	Zero-based page number.Default: `0`
`q`	`string`	Full-text search query.
`qf`	`string`	Comma-separated fields used by the full-text query.
`sort`	`string`	Sort expression. Prefix a field with "-" for descending order. Counter-backed endpoints can sort by counters.total.<field> or by the counter shorthand itself, for example sort=-engagement on post/social data or sort=-click on organic data.
`filters`	`string`	AND filters on item fields. Use semicolons between filters and ".." for ranges. Send the separators ":", ";", "," and ".." as raw characters: search endpoints read the raw query string and treat percent-encoded separators as literal value characters. Percent-encode only characters inside values, such as spaces (%20). On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203". On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`excludes`	`string`	Exclude results when a field contains a value. On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`fields`	`string`	Comma-separated fields to include in each returned item.
`exists`	`string`	Comma-separated fields that must exist in each returned item. Fields must belong to the endpoint entity; invalid fields return 400 Bad Request.

Response fields

Field	Type	Description
`total`	`int`	Total number of media found.
`rows`	`Media[]`	Media items found on the requested page.
->`id`	`string`	Media ID.
->`url`	`string`	Media URL.
->`type`	`string`	Media type.
->`tag`	`string[]`	Associated tags.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/media?fields=id,url,type,tag&size=50' \
2  --header 'Authorization: Bearer YOUR_API_TOKEN'

GET/media/tagsBearer required

14.2.Get media tags

Return media tags for autocomplete and asset filtering.

Query parameters

Field	Type	Description
`size`	`int`	Maximum number of results to return.Default: `20 or endpoint-specific`
`q`	`string`	Full-text search query.
`qf`	`string`	Comma-separated fields used by the full-text query.
`filters`	`string`	AND filters on item fields. Use semicolons between filters and ".." for ranges. Send the separators ":", ";", "," and ".." as raw characters: search endpoints read the raw query string and treat percent-encoded separators as literal value characters. Percent-encode only characters inside values, such as spaces (%20). On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203". On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`excludes`	`string`	Exclude results when a field contains a value. On post-backed counter filters, documented counter names are resolved for counters.total.field, counters.graph.counter, counters.histogram.field, and counters.period.field.
`exists`	`string`	Comma-separated fields that must exist in each returned item. Fields must belong to the endpoint entity; invalid fields return 400 Bad Request.

Response fields

Field	Type	Description
`total`	`int`	Total number of tags found.
`rows.key`	`string`	Tag value.
`rows.doc_count`	`int`	Number of media items using the tag.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/media/tags?size=100' \
2  --header 'Authorization: Bearer YOUR_API_TOKEN'

15.Uploads

6 endpoints

Upload images, videos, and documents before attaching them to posts.

POST/upload/imageBearer required

15.1.Upload an image

Upload a base64 image and receive the Fontan slug used by posts and shortlinks.

Body parameters

Field	Type	Description
`b64Image`*	`string`	Base64 encoded image.
`keepFormat`	`bool`	Keep the original format when possible.
`faceDetect`	`bool`	Run face detection/cropping assistance.Default: `true`

Response fields

Field	Type	Description
`slug`	`string`	Fontan image slug.
`url`	`string`	Image URL when available.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/upload/image' \
2  --header 'Content-Type: application/json' \
3  --header 'Authorization: Bearer YOUR_API_TOKEN' \
4  --data '{
5    "b64Image": "data:image/png;base64,iVBORw0KGgo...",
6    "keepFormat": true
7  }'

POST/upload/video/tokenBearer required

15.2.Create upload video token

Create or resume an upload session. The response includes chunkSize, which defines the maximum chunk size to send.

Body parameters

Field	Type	Description
`name`*	`string`	File name.
`type`*	`string`	Video MIME type.
`size`*	`int`	File size in bytes.
`md5sum`*	`string`	Unique video ID, md5 encoded.
`duration`	`int`	Video duration in seconds.
`width`	`int`	Video width in pixels.
`height`	`int`	Video height in pixels.
`title`	`string`	Video title.
`description`	`string`	Video description.
`customTag`	`string[]`	Video custom tags.

Response fields

Field	Type	Description
`token`	`string`	Upload token.
`size`	`int`	File size in bytes.
`chunkSize`	`int`	Chunk size in bytes.
`chunkIndex`	`int`	Next chunk index.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/upload/video/token' \
2  --header 'Content-Type: application/json' \
3  --header 'Authorization: Bearer YOUR_API_TOKEN' \
4  --data '{
5    "md5sum": "64bed820ce612754d1e3e957edfc69c7",
6    "name": "35427-407130886_small.mp4",
7    "size": 1338788,
8    "type": "video/mp4",
9    "title": "My video title",
10    "description": "My video description",
11    "customTag": ["foo", "bar"]
12  }'

POST/upload/video/existsBearer required

15.3.Check uploaded video existence

Check if a video already exists before starting a chunked upload.

Body parameters

Field	Type	Description
`md5sum`*	`string`	Unique video ID, md5 encoded.
`name`*	`string`	File name.

Response fields

Field	Type	Description
`exists`	`bool`	Whether the video already exists.
`id`	`string`	Existing video ID when found.
`url`	`string`	Existing video URL when found.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/upload/video/exists' \
2  --header 'Content-Type: application/json' \
3  --header 'Authorization: Bearer YOUR_API_TOKEN' \
4  --data '{
5    "md5sum": "64bed820ce612754d1e3e957edfc69c7",
6    "name": "35427-407130886_small.mp4"
7  }'

POST/upload/video/chunkBearer required

15.4.Upload video chunk

Upload one base64 chunk for a video upload session. The final response includes the video id and URL.

Body parameters

Field	Type	Description
`token`*	`string`	Upload token.
`chunk`*	`int`	Chunk number.
`data`*	`string`	Chunk bytes as base64.

Response fields

Field	Type	Description
`size`	`int`	Uploaded size after this chunk.
`id`	`string`	Video ID, returned when the last chunk has been uploaded.
`url`	`string`	Video URL, returned when the last chunk has been uploaded.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/upload/video/chunk' \
2  --header 'Content-Type: application/json' \
3  --header 'Authorization: Bearer YOUR_API_TOKEN' \
4  --data '{
5    "token": "e5bab8115967331ce0db284e03622cf0",
6    "chunk": 1,
7    "data": "AAAAIGZ0eXBtcDQyAAAAAG1wNDJtcDQxaXNvbWF2YzEAABF9b..."
8  }'

POST/upload/document/tokenBearer required

15.5.Create upload document token

Create or resume a document upload session. The response includes chunkSize for chunked upload.

Body parameters

Field	Type	Description
`name`*	`string`	File name.
`type`*	`string`	Document MIME type, commonly application/pdf.
`size`*	`int`	File size in bytes.
`md5sum`*	`string`	Unique document ID, md5 encoded.
`title`	`string`	Document title.
`description`	`string`	Document description.
`pageCount`	`int`	Number of pages in the document.

Response fields

Field	Type	Description
`token`	`string`	Upload token.
`size`	`int`	File size in bytes.
`chunkSize`	`int`	Chunk size in bytes.
`chunkIndex`	`int`	Next chunk index.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/upload/document/token' \
2  --header 'Content-Type: application/json' \
3  --header 'Authorization: Bearer YOUR_API_TOKEN' \
4  --data '{
5    "md5sum": "64bed820ce612754d1e3e957edfc69c7",
6    "name": "press-release.pdf",
7    "size": 1024000,
8    "type": "application/pdf",
9    "title": "Press release",
10    "pageCount": 3
11  }'

POST/upload/document/chunkBearer required

15.6.Upload document chunk

Upload one base64 chunk for a document upload session. The final response includes the document id and URL.

Body parameters

Field	Type	Description
`token`*	`string`	Upload token.
`chunk`*	`int`	Chunk number.
`data`*	`string`	Chunk bytes as base64.

Response fields

Field	Type	Description
`size`	`int`	Uploaded size after this chunk.
`id`	`string`	Document ID, returned when the last chunk has been uploaded.
`url`	`string`	Document URL, returned when the last chunk has been uploaded.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/upload/document/chunk' \
2  --header 'Content-Type: application/json' \
3  --header 'Authorization: Bearer YOUR_API_TOKEN' \
4  --data '{
5    "token": "e5bab8115967331ce0db284e03622cf0",
6    "chunk": 1,
7    "data": "JVBERi0xLjQKJc..."
8  }'