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

57endpoints

9resources

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

57 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 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 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 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.

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.
`filters`	`string`	AND filters on item fields. Use semicolons between filters and ".." for ranges.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203".
`excludes`	`string`	Exclude results when a field contains a value.
`fields`	`string`	Comma-separated fields to include in each returned item.
`exists`	`string`	Comma-separated fields that must exist in each returned item.

3.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

4.Brands

2 endpoints

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

GET/brandsBearer required

4.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.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203".
`excludes`	`string`	Exclude results when a field contains a value.
`fields`	`string`	Comma-separated fields to include in each returned item.
`exists`	`string`	Comma-separated fields that must exist in each returned item.
`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

4.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'

5.Social accounts

5 endpoints

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

GET/social-accountsBearer required

5.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.
`filters`	`string`	AND filters on item fields. Use semicolons between filters and ".." for ranges.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203".
`excludes`	`string`	Exclude results when a field contains a value.
`fields`	`string`	Comma-separated fields to include in each returned item.
`exists`	`string`	Comma-separated fields that must exist in each returned item.
`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, twitter, 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

5.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

5.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

5.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.
`filters`	`string`	AND filters on item fields. Use semicolons between filters and ".." for ranges.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203".
`excludes`	`string`	Exclude results when a field contains a value.
`fields`	`string`	Comma-separated fields to include in each returned item.
`exists`	`string`	Comma-separated fields that must exist in each returned item.

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

5.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.
`filters`	`string`	AND filters on item fields. Use semicolons between filters and ".." for ranges.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203".
`excludes`	`string`	Exclude results when a field contains a value.
`fields`	`string`	Comma-separated fields to include in each returned item.
`exists`	`string`	Comma-separated fields that must exist in each returned item.

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'

6.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

6.1.Search posts

Search posts published or scheduled through Nonli.

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.
`filters`	`string`	AND filters on item fields. Use semicolons between filters and ".." for ranges.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203".
`excludes`	`string`	Exclude results when a field contains a value.
`fields`	`string`	Comma-separated fields to include in each returned item.
`exists`	`string`	Comma-separated fields that must exist in each returned item.
`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%3Apolitique&size=20&page=0&fields=author,createdAt,updatedAt,message,postType,publishedAt,socialAccount,status,title&sort=-publishedAt,createdAt&filters=brandId%3A1%3Bstatus%3A200' \
2  --header 'Authorization: Bearer YOUR_API_TOKEN'

GET/posts/:postIdBearer required

6.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

6.3.Get post categories

Return category aggregations used by post filters and dashboards.

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.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203".
`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 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

6.4.Get post brands

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

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.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203".
`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 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

6.5.Get post users

Return user aggregations for post author and collaboration filters.

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.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203".
`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 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

6.6.Get post languages

Return language aggregations for post filters.

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.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203".
`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 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

6.7.Get post histogram

Return time-bucketed post counts or counter values for graphing.

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.
`filters`	`string`	AND filters on item fields. Use semicolons between filters and ".." for ranges.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203".
`excludes`	`string`	Exclude results when a field contains a value.
`fields`	`string`	Comma-separated fields to include in each returned item.
`exists`	`string`	Comma-separated fields that must exist in each returned item.
`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

6.8.Get post aggregation

Return generic aggregations for post dashboards and filter facets.

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.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203".
`excludes`	`string`	Exclude results when a field contains a value.
`exists`	`string`	Comma-separated fields that must exist in each returned item.
`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

6.9.Get post stats

Return aggregated post performance statistics for dashboard widgets.

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.
`filters`	`string`	AND filters on item fields. Use semicolons between filters and ".." for ranges.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203".
`excludes`	`string`	Exclude results when a field contains a value.
`fields`	`string`	Comma-separated fields to include in each returned item.
`exists`	`string`	Comma-separated fields that must exist in each returned item.

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

6.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

6.11.Get post tags

Return matching tags for autocomplete and reporting filters.

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.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203".
`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 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

6.12.Get post topics

Return matching topics for autocomplete and reporting filters.

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.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203".
`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 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

6.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

6.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

6.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  }'

7.Shortlinks

9 endpoints

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

GET/shortlinksBearer required

7.1.Search shortlinks

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

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.
`filters`	`string`	AND filters on item fields. Use semicolons between filters and ".." for ranges.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203".
`excludes`	`string`	Exclude results when a field contains a value.
`fields`	`string`	Comma-separated fields to include in each returned item.
`exists`	`string`	Comma-separated fields that must exist in each returned item.

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

7.2.Get a shortlink

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

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

7.3.Get shortlink stats

Return aggregated shortlink performance statistics.

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.
`filters`	`string`	AND filters on item fields. Use semicolons between filters and ".." for ranges.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203".
`excludes`	`string`	Exclude results when a field contains a value.
`fields`	`string`	Comma-separated fields to include in each returned item.
`exists`	`string`	Comma-separated fields that must exist in each returned item.

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

7.4.Get shortlink authors

Return author aggregations used by shortlink filters.

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.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203".
`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 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

7.5.Get shortlink brands

Return brand aggregations used by shortlink filters.

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.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203".
`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 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

7.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

7.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

7.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

7.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  }'

8.Listening

6 endpoints

Search social-network performance and organic website content signals.

GET/listening/socialBearer required

8.1.Get social listening

Search social posts and counters collected from supported social networks.

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.
`filters`	`string`	AND filters on item fields. Use semicolons between filters and ".." for ranges.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203".
`excludes`	`string`	Exclude results when a field contains a value.
`fields`	`string`	Comma-separated fields to include in each returned item.
`exists`	`string`	Comma-separated fields that must exist in each returned item.

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, twitter, instagram, etc.
`rows.counters.total.field`	`string`	Counter field.
`rows.counters.total.value`	`int`	Counter total value.

Example

bash

1curl --location 'https://api.nonli.com/v2.1/listening/social?filters=publishedAt%3A-15%20minutes..now%3BsocialAccount.type%3Afacebook&filtersOr=counters.graph.counter%3Afacebook_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,socialAccount.category.fr&sort=-counters.total.facebook_engagement' \
2  --header 'Authorization: Bearer YOUR_API_TOKEN'

GET/listening/organicBearer required

8.2.Get organic listening

Search website content indexed by Organic Listening.

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.
`filters`	`string`	AND filters on item fields. Use semicolons between filters and ".." for ranges.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203".
`excludes`	`string`	Exclude results when a field contains a value.
`fields`	`string`	Comma-separated fields to include in each returned item.
`exists`	`string`	Comma-separated fields that must exist in each returned item.
`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.value`	`int`	Counter total value.

Example

bash

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

GET/listening/organic/:organicIdBearer required

8.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

8.4.Get organic stats

Return aggregated Organic Listening performance statistics.

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.
`filters`	`string`	AND filters on item fields. Use semicolons between filters and ".." for ranges.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203".
`excludes`	`string`	Exclude results when a field contains a value.
`fields`	`string`	Comma-separated fields to include in each returned item.
`exists`	`string`	Comma-separated fields that must exist in each returned item.

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

8.5.Get organic aggregation

Return generic aggregations for Organic Listening dashboards and filters.

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.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203".
`excludes`	`string`	Exclude results when a field contains a value.
`exists`	`string`	Comma-separated fields that must exist in each returned item.
`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

8.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'

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%3Afr&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.Bots

6 endpoints

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

GET/botsBearer required

10.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.
`filters`	`string`	AND filters on item fields. Use semicolons between filters and ".." for ranges.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203".
`excludes`	`string`	Exclude results when a field contains a value.
`fields`	`string`	Comma-separated fields to include in each returned item.
`exists`	`string`	Comma-separated fields that must exist in each returned item.
`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

10.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

10.3.Create bots in bulk

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

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.

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        "fieldMapping": [
36          {
37            "source": "title",
38            "target": "message"
39          }
40        ],
41        "sourceMessage": "title",
42        "sourceTitle": "title",
43        "sourceImage": "og_image"
44      }
45    ]
46  }'

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

10.4.Update bots in bulk

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

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.

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

10.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

10.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'

11.Media

2 endpoints

Search reusable media and metadata used by the publishing composer.

GET/mediaBearer required

11.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.
`filters`	`string`	AND filters on item fields. Use semicolons between filters and ".." for ranges.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203".
`excludes`	`string`	Exclude results when a field contains a value.
`fields`	`string`	Comma-separated fields to include in each returned item.
`exists`	`string`	Comma-separated fields that must exist in each returned item.

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

11.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.
`filtersOr`	`string`	OR filters on item fields. Example: "status:200,203".
`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 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'

12.Uploads

6 endpoints

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

POST/upload/imageBearer required

12.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

12.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

12.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

12.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

12.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

12.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  }'