Quickstart

In this guide you create a credential, request an access token, send a turn and read the answer. The whole API lives under https://api.niucore.com/api/v1 and uses Authorization: Bearer.

1. 1

   Create a credential

   Go to Profile → API and integrations in the application, name the credential and pick its scopes. On save you get the client_id and the client_secret.

   The secret is shown once

   It is not stored in the clear anywhere, so it cannot be shown again. If you lose it, rotate the credential and update your integration.

   Store them as environment variables

   export NIUCORE_CLIENT_ID="nc_7f3c1a9b8e2d4056"
   export NIUCORE_CLIENT_SECRET="ncs_R2xk...."

2. 2

   Request an access token

   The token lasts one hour by default and is not refreshed: when it expires, you request another with the same credentials.

   cURLPythonNode.js

   curl -sS -X POST 'https://api.niucore.com/api/oauth/token' \
     -u "$NIUCORE_CLIENT_ID:$NIUCORE_CLIENT_SECRET" \
     -d 'grant_type=client_credentials'

   JSON

   {
     "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
     "token_type": "Bearer",
     "expires_in": 3600,
     "scope": "chat:read chat:write libraries:read"
   }

3. 3

   Confirm who you are

   GET /me is the first request worth making: it validates the token and shows the scopes you will actually operate with. If a scope you asked for is missing here, the user's role narrowed it.

   cURLPythonNode.js

   curl -sS 'https://api.niucore.com/api/v1/me' \
     -H "Authorization: Bearer $NIUCORE_ACCESS_TOKEN"

4. 4

   Send your first turn

   A turn is sent to a chat_id. If the chat does not exist, it is created with that id — so you can generate a UUID yourself and start. The Idempotency-Key header is required.

   cURLPythonNode.js

   CHAT_ID=$(uuidgen | tr 'A-Z' 'a-z')
   
   curl -sS -X POST "https://api.niucore.com/api/v1/chats/$CHAT_ID/messages" \
     -H "Authorization: Bearer $NIUCORE_ACCESS_TOKEN" \
     -H 'Content-Type: application/json' \
     -H "Idempotency-Key: $(uuidgen)" \
     -d '{
       "content": "Hola, ¿en qué me podés ayudar?",
       "permission_mode": "auto"
     }'

   Note

   The synchronous send blocks until the full answer and only accepts permission_mode: "auto". To see the text as it is generated, or to let the turn ask permission before running tools, use the streaming send.

#Environments

#What's next