Constella API Documentation

Welcome to the Constella API! Here you can programmatically insert new notes into your Constella workspace or search existing notes using AI-powered semantic search.

Use this API to build on top of your interconnected workspace.

Base URL

All endpoints described below should be prefixed with the base URL:

https://constella-external-api-653702ba9b9b.herokuapp.com

So, for example, an endpoint might look like:

POST https://constella-external-api-653702ba9b9b.herokuapp.com/constella-external-api/insert-note

Authentication

Every request requires an API key sent via the request header x_access_key.

1. Obtain your API key by:

   • Opening the Constella desktop app
   • Clicking the gear icon in the top right
   • Navigating to Account > Connect
   • Creating an API Key under Zapier / API

2. Use this API key in the x_access_key header for all endpoints below.

Endpoints

1. Insert Note

Create a new note in your Constella workspace programmatically.

Endpoint

POST /constella-external-api/insert-note

Required Header

x_access_key: YOUR_API_KEY

Request Body

Field	Type	Required	Description
title	string	yes	The title of the note you want to insert
content	string	no	The content/body of the note

Example Request

{
    "title": "My First External Note",
    "content": "This note was inserted via the API!"
}

Successful Response

{
    "success": true
}

2. Search Notes

Search through your existing notes using a semantic vector search. This uses AI embeddings to find the notes most relevant to your query.

Endpoint

POST /constella-external-api/search-notes

Required Header

x_access_key: YOUR_API_KEY

Request Body

Field	Type	Required	Default	Description
query	string	yes	-	The text to search against your Constella notes
results_count	integer	no	10	Maximum number of results to return
similarity_strength	float	no	0.5	A value (typically between 0.0 and 1.0) that determines how similar a note must be to the query to be considered relevant
output_type	string	no	"list"	Determines the format of the response. Possible values: "list" or "text"

Example Request (List Format)

{
    "query": "meeting notes",
    "results_count": 5,
    "similarity_strength": 0.7,
    "output_type": "list"
}

Example Request (Text Format)

{
    "query": "project ideas",
    "results_count": 3,
    "similarity_strength": 0.8,
    "output_type": "text"
}

Successful Response (List Format)

{
    "results": [
        {
            "id": "1111-2222-3333-4444",
            "title": "Q1 Meeting Notes",
            "content": "Notes from Q1 planning session...",
            "tags": [
                {
                    "name": "meeting",
                    "color": "#12B886",
                    "id": "tag-0001"
                }
            ]
        },
        {
            "id": "5555-6666-7777-8888",
            "title": "Another Meeting Note",
            "content": "Some follow-up tasks from the last meeting...",
            "tags": []
        }
    ]
}

Response fields:

• results: An array of notes matching the query
• id: The note's unique ID in Constella
• title: The note title
• content: The text content of the note
• tags: An array of tags associated with the note, containing:
  • name: The tag's name
  • color: The display color for the tag
  • id: The tag's unique ID

Successful Response (Text Format)

{
    "results": "Title: Q1 Meeting Notes\nContent: Notes from Q1 planning session...\nTags: meeting\nId: 1111-2222-3333-4444\n\nTitle: Another Meeting Note\nContent: Some follow-up tasks...\nTags: \nId: 5555-6666-7777-8888\n\n"
}

Error Responses

You may receive:

• 401 or 403 HTTP error if:
  • Your API key is missing or invalid
  • Your subscription/account does not have permission
• 500 HTTP error for general server errors

Example Usage

Insert a Note

curl -X POST \
  https://constella-external-api-653702ba9b9b.herokuapp.com/constella-external-api/insert-note \
  -H 'x_access_key: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "title": "My First External Note",
    "content": "This note was inserted via the API!"
  }'

Example Response:

{
    "success": true
}

Search Notes

curl -X POST \
  https://constella-external-api-653702ba9b9b.herokuapp.com/constella-external-api/search-notes \
  -H 'x_access_key: YOUR_API_KEY_HERE' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "project ideas",
    "results_count": 3,
    "similarity_strength": 0.8,
    "output_type": "list"
  }'

Example Response:

{
    "results": [
        {
            "id": "abcdef-12345",
            "title": "Project Idea 1",
            "content": "We should explore building an AI-based solution...",
            "tags": []
        },
        {
            "id": "abcdef-67890",
            "title": "Future Projects",
            "content": "Brainstorming session on next-gen ideas...",
            "tags": []
        }
    ]
}

That's it! You're all set to create and search notes with Constella's external API. Happy building!