# Nonli Developer API

> API documentation for clients and AI agents integrating with Nonli.

Base URL: https://api.nonli.com/v2.1
OpenAPI: https://www.nonli.com/api-docs/openapi.json
Human documentation: https://www.nonli.com/en/developers

Authentication:
- Create an API token from the Nonli back office.
- Send it on authenticated calls using Authorization: Bearer YOUR_API_TOKEN.
- API tokens represent a company role, not a web user session. Do not use /me with Bearer tokens.
- To validate a token, call GET /brands?size=1&fields=id,name.

Common query grammar:
- filters uses semicolon-separated AND filters, for example filters=brandId:1;status:200.
- filtersOr uses OR values, for example filtersOr=status:200,203.
- ranges use two dots, for example publishedAt:2024-05-01T00:00:00Z..2024-05-31T23:59:59Z.
- fields limits returned fields and should be used by agents to reduce payload size.

Conventions:
- List endpoints return total plus a rows array; page with size and a zero-based page until total items are collected.
- Timestamps are UTC ISO-8601, for example 2026-05-27T23:59:59Z.
- Identifiers are string UUIDs for posts, shortlinks, and organic items, and integers for brands, social accounts, and themes.
- The API token is a bearer credential; store it securely, rotate it from the back office, and do not put it in query strings.

Errors:
- Branch on the HTTP status code rather than parsing error message text.
- 400 bad request, 401 unauthorized (check or rotate the API token), 403 forbidden, 404 not found, 429 rate limited (back off and retry), 5xx server error.

Core endpoints:
- GET /brands: Search brands. Return the brands visible to the API token role in the authenticated company.
- GET /brands/:brandId: Get a brand. Return one brand with optional embedded configuration used for publishing, shortlinks, smart images, and URL parameters.
- GET /social-accounts: Search social accounts. Return social accounts available to the authenticated company and user.
- GET /social-accounts/:socialAccountId: Get a social account. Return one connected social account with publishing metadata.
- GET /social-accounts/publishing-quota: Get publishing quota. Return publishing quota information for selected social accounts before scheduling posts.
- GET /social-accounts/youtube/playlists: Get YouTube playlists. Return YouTube playlists for connected YouTube social accounts.
- GET /social-accounts/pinterest/boards: Get Pinterest boards. Return Pinterest boards for connected Pinterest social accounts.
- GET /posts: Search posts. Search posts published or scheduled through Nonli.
- GET /posts/:postId: Get a post. Return one post by ID with optional filters and field selection.
- GET /posts/categories: Get post categories. Return category aggregations used by post filters and dashboards.
- GET /posts/brands: Get post brands. Return brand aggregations for posts visible to the API token role.
- GET /posts/users: Get post users. Return user aggregations for post author and collaboration filters.
- GET /posts/languages: Get post languages. Return language aggregations for post filters.
- GET /posts/histogram: Get post histogram. Return time-bucketed post counts or counter values for graphing.
- GET /posts/aggregation: Get post aggregation. Return generic aggregations for post dashboards and filter facets.
- GET /posts/stats: Get post stats. Return aggregated post performance statistics for dashboard widgets.
- POST /posts/check: Check post content. Validate post content before publishing. The BO uses this endpoint to surface publication warnings.
- GET /posts/tags: Get post tags. Return matching tags for autocomplete and reporting filters.
- GET /posts/topics: Get post topics. Return matching topics for autocomplete and reporting filters.
- POST /posts/bulk: Create posts in bulk. Create a collection of posts. Use postType "flying" with a shortlink mappingId to publish a flying link.
- PUT /posts/bulk: Update posts in bulk. Update a collection of posts. Send post.id and, when available, createdAt to optimize lookup.
- DELETE /posts/bulk: Delete posts in bulk. Delete a collection of posts. The async flag can be used for background deletion.
- GET /shortlinks: Search shortlinks. Search shortlinks and retrieve counters, target URLs, metadata, and publication information.
- GET /shortlinks/:shortlinkId: Get a shortlink. Return one shortlink by ID with optional counters and field selection.
- GET /shortlinks/stats: Get shortlink stats. Return aggregated shortlink performance statistics.
- GET /shortlinks/authors: Get shortlink authors. Return author aggregations used by shortlink filters.
- GET /shortlinks/brands: Get shortlink brands. Return brand aggregations used by shortlink filters.
- POST /shortlinks: Create a shortlink. Create or extract a shortlink for a target URL.
- POST /shortlinks/bulk: Create shortlinks in bulk. Create several shortlinks in one request.
- PUT /shortlinks/:shortlinkId: Update a shortlink. Update target URL, metadata, images, brand association, and sponsor information for a shortlink.
- POST /shortlinks/:shortlinkId/generate-message: Generate a message for a shortlink. Generate suggested social copy for a shortlink and content type.
- GET /listening/social: Get social listening. Search social posts and counters collected from supported social networks.
- GET /listening/organic: Get organic listening. Search website content indexed by Organic Listening.
- GET /listening/organic/:organicId: Get organic content. Return one indexed organic content item by ID.
- GET /listening/organic/stats: Get organic stats. Return aggregated Organic Listening performance statistics.
- GET /listening/organic/aggregation: Get organic aggregation. Return generic aggregations for Organic Listening dashboards and filters.
- GET /listening/organic/suggest/:field: Suggest organic filter values. Return autocomplete suggestions for an Organic Listening field.
- GET /themes: Search themes. Return team, bot, or public themes visible to the API token role.
- GET /themes/:themeId: Get a theme. Return one saved theme by ID.
- POST /themes: Create a theme. Create a saved theme from listening or post filters.
- PUT /themes/:themeId: Update a theme. Update a saved theme and rebuild its query strings when the value changes.
- DELETE /themes/:themeId: Delete a theme. Delete a saved theme.
- GET /themes/roles: Get theme roles. Return roles that can be associated with team-scoped themes.
- GET /bots: Search bots. Return bots visible to the API token role in the authenticated company.
- GET /bots/:botId: Get a bot. Return one bot by UUID.
- POST /bots/bulk: Create bots in bulk. Create one or more bots. Source and target URNs must reference resources visible to the API token role.
- PUT /bots/bulk: Update bots in bulk. Update one or more bots. Each item must include the bot UUID and only the fields to change.
- DELETE /bots/:botId: Delete a bot. Delete one bot by UUID. A successful deletion returns HTTP 204 with no response body.
- GET /bots/info: Get bot configuration info. Return schedule periods, target validation rules, and bot configuration constraints used to build valid bot payloads.
- GET /media: Search media. Return media items available to the current company and user.
- GET /media/tags: Get media tags. Return media tags for autocomplete and asset filtering.
- POST /upload/image: Upload an image. Upload a base64 image and receive the Fontan slug used by posts and shortlinks.
- POST /upload/video/token: Create upload video token. Create or resume an upload session. The response includes chunkSize, which defines the maximum chunk size to send.
- POST /upload/video/exists: Check uploaded video existence. Check if a video already exists before starting a chunked upload.
- POST /upload/video/chunk: Upload video chunk. Upload one base64 chunk for a video upload session. The final response includes the video id and URL.
- POST /upload/document/token: Create upload document token. Create or resume a document upload session. The response includes chunkSize for chunked upload.
- POST /upload/document/chunk: Upload document chunk. Upload one base64 chunk for a document upload session. The final response includes the document id and URL.

Recommended agent flow: load the Bearer token from a secret store, request only needed fields, page through results with size/page, and respect rate limits.