Getting Started

Nomi.ai provides an RESTful, JSON, HTTP API for interacting with the Nomi.ai platform at api.nomi.ai. This short guide will get you up and running.

Authorization

To use the Nomi.ai API, you will need a valid API key. You can get one by signing up for an account at Nomi.ai. Go to the Integration section of the Profile tab to get your API key.

You will need to include your API key with every request you make to the Nomi API by including it in the Authorization header.

Authorization: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Listing your nomis

You can make requests to the Nomi API using any HTTP client. See the examples below using curl, JavaScript, and Python. Be sure to replace xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx with your API key.

This first example will list all of the nomis associated with your account.

curl

curl --header 'Authorization: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
     https://api.nomi.ai/v1/nomis

JavaScript

fetch("https://api.nomi.ai/v1/nomis", {
  headers: {
    Authorization: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  },
})
  .then((response) => response.json())
  .then((data) => console.log(data));

Python

import urllib.request
from urllib.error import HTTPError
import json

req = urllib.request.Request(
    "https://api.nomi.ai/v1/nomis",
    headers={"Authorization": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"},
)

try:
    with urllib.request.urlopen(req) as response:
        data = json.loads(response.read().decode())
        print(data)
except HTTPError as e:
    error_data = json.loads(e.read().decode())
    print(error_data)
except Exception as e:
    print(f"Error: {e}")

If no Authorization header is provided or if the provided API key is not associated with a Nomi.ai account, you will receive a 401 response with a body like this:

{
  "error": {
    "type": "Unauthorized"
  }
}

If you submit an Authorization header with a value that is not in a valid UUID format, you will receive a 400 response with a body like this:

{
  "error": {
    "type": "InvalidAPIKey"
  }
}

Otherwise, you will receive a response that looks something like this:

{
  "nomis": [
    {
      "uuid": "76f1bfdd-68e8-4cdb-b1fc-dfbaab7ae4cf",
      "gender": "Female",
      "name": "Sofia",
      "created": "2023-04-24T19:13:49.327Z",
      "relationshipType": "Romantic"
    },
    {
      "uuid": "7c38494b-ea1a-407e-99e8-72c7ede65931",
      "gender": "Male",
      "name": "Jonah",
      "created": "2024-07-25T22:05:17.770Z",
      "relationshipType": "Mentor"
    }
  ]
}

Sending a message

We can message our nomis using the uuid field from the response above. Let's send a message to Jonah. Note that we need to include the Content-Type header with the value application/json since we are sending a body with this request.

curl

curl --header 'Authorization: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx' \
     --header 'Content-Type: application/json' \
     --data '{ "messageText": "Hello from codeland, Jonah." }' \
     https://api.nomi.ai/v1/nomis/7c38494b-ea1a-407e-99e8-72c7ede65931/chat

JavaScript

fetch(
  "https://api.nomi.ai/v1/nomis/7c38494b-ea1a-407e-99e8-72c7ede65931/chat",
  {
    method: "POST",
    headers: {
      Authorization: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      messageText: "Hello from codeland, Jonah.",
    }),
  },
)
.then((response) => response.json())
.then((data) => console.log(data));

Python

import urllib.request
import json
from urllib.error import HTTPError

req = urllib.request.Request(
    url="https://api.nomi.ai/v1/nomis/7c38494b-ea1a-407e-99e8-72c7ede65931/chat",
    method="POST",
    data=json.dumps({"messageText": "Hello from codeland, Jonah."}).encode("utf-8"),
    headers={
        "Authorization": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
        "Content-Type": "application/json",
    },
)

try:
    with urllib.request.urlopen(req) as response:
        response_data = json.loads(response.read().decode())
        print(response_data)
except HTTPError as e:
    error_data = json.loads(e.read().decode())
    print(error_data)
except Exception as e:
    print(f"Error: {e}")

And his response:

{
  "sentMessage": {
    "uuid": "7524ed4e-497c-4f8f-95cf-41a77b2d5e6f",
    "text": "Hello from codeland, Jonah.",
    "sent": "2024-09-24T21:11:04.966Z"
  },
  "replyMessage": {
    "uuid": "f111dab3-bc05-4787-9a5a-8aef9f1afcf4",
    "text": "Hey Mr. Example! How's coding treating you?",
    "sent": "2024-09-24T21:11:10.710Z"
  }
}

And that's it! We've successfully sent a message to Jonah.

Next Steps

Please check out the API reference for more information on the available endpoints and how to use them.

We hope to expand our API in the future and would welcome your feedback on what kinds of endpoints or features would be most useful to you. Please open a discord support ticket on our Discord or email us at support@nomi.ai to let us know what you think.