Introduction

The vivenu API provides a set of REST endpoints to access the platform. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Base URL:

https://vivenu.com/api or https://vivenu.dev/api

Authentication

We use API keys to handle authentication. Sellers can create and update their API keys through the vivenu Dashboard under Settings > Developers > API Keys, or via the API.

You must send an HTTP Header Authorization with a Bearer prefix within every request. Requests against private endpoints that are not authenticated will fail with 401 - Unauthorized.

Seller API keys can use full seller access (seller-admin equivalent) or granular permissions that allow only the resource:action values you assign. Requests that need a permission the key does not have fail with 403. Organization API keys authenticate organization-scoped endpoints and cannot use granular permissions.

API keys are intended for server-side communication only. Never expose them to clients, for example through JavaScript intended for the browser. The plaintext secret is shown only at creation.

ORG API Keys

Endpoints that accept Organization API Keys are marked with the following label through out this documentation:

Public API

The vivenu API includes private and public endpoints. Public endpoints are open to the public and don't require authentication. Those are marked with this label throughout this documentation:

Pagination

All top-level API resources support bulk fetching using "get all" API methods. These API methods share the same top & skip pattern for pagination.

Every request response will contain at least two keys: The requested data and the total number of documents matching your current query. "Get all" methods will limit the number of returned documents to 25, however some endpoints support increasing the limit to up to 100 using &top=100.

To traverse through all documents you can use the skip parameter to skip a given number of documents.

Array query parameters

Some API resources support multiple values for a query parameter through arrays.

To use them, you pass multiple parameters with the query name, adding [] to mark them as items of an array:

https://vivenu.com/api/example?arrayParam[]=value1&arrayParam[]=value2

Nested key query parameters

Some API resources support nested key of an object as a query parameter.

To use them, you pass a query parameter as follow:

https://vivenu.com/api/example?object[key]=value