{"id":17026034,"url":"https://github.com/TimeSurgeLabs/athenadb","last_synced_at":"2026-04-13T01:30:18.075Z","repository":{"id":212010809,"uuid":"730439488","full_name":"TimeSurgeLabs/athenadb","owner":"TimeSurgeLabs","description":"🦉⚡️Serverless, distributed vector database as an API","archived":false,"fork":false,"pushed_at":"2024-02-19T17:55:58.000Z","size":72,"stargazers_count":166,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2024-02-20T04:28:45.970Z","etag":null,"topics":["cloudflare","cloudflare-ai","cloudflare-d1","cloudflare-vectorize","cloudflare-workers","cloudflare-workers-ai","embeddings","vector-database"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"agpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/TimeSurgeLabs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2023-12-11T23:40:39.000Z","updated_at":"2024-02-20T04:16:58.000Z","dependencies_parsed_at":"2024-02-19T04:28:13.688Z","dependency_job_id":"b2ea4834-7b83-4149-8c05-56d4e1b84a2b","html_url":"https://github.com/TimeSurgeLabs/athenadb","commit_stats":null,"previous_names":["timesurgelabs/athenadb"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimeSurgeLabs%2Fathenadb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimeSurgeLabs%2Fathenadb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimeSurgeLabs%2Fathenadb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/TimeSurgeLabs%2Fathenadb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/TimeSurgeLabs","download_url":"https://codeload.github.com/TimeSurgeLabs/athenadb/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219847890,"owners_count":16556345,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cloudflare","cloudflare-ai","cloudflare-d1","cloudflare-vectorize","cloudflare-workers","cloudflare-workers-ai","embeddings","vector-database"],"created_at":"2024-10-14T07:30:22.724Z","updated_at":"2026-04-13T01:30:18.017Z","avatar_url":"https://github.com/TimeSurgeLabs.png","language":"TypeScript","readme":"\u003ch1 align=\"center\"\u003e🦉AthenaDB⚡️\u003c/h1\u003e\n\u003ch3 align=\"center\"\u003eServerless, distributed Vector Database as an API written with Cloudflare Workers, Workers AI, D1, and Vectorize.\u003c/h3\u003e\n\nAthenaDB is a simple, serverless, distributed vector database that can be used as an API. It is written with [Cloudflare Workers AI](https://ai.cloudflare.com), [D1](https://developers.cloudflare.com/d1/), [Vectorize](https://developers.cloudflare.com/vectorize/).\n\n## Features\n\n- **Simple API Endpoints**: AthenaDB provides straightforward endpoints for various database operations, making it accessible for developers of all skill levels.\n- **Distributed Nature**: With data replication across multiple data centers, AthenaDB ensures high availability and resilience.\n- **Built-In Data Replication**: Due to Cloudflare Workers’ underlying architecture, data is replicated across data centers automatically.\n- **Scalability**: AthenaDB is designed to handle large amounts of vector text data, making it suitable for projects with high data volumes.\n- **Serverless Architecture**: With AthenaDB being serverless, you don't have to worry about managing infrastructure, allowing for more focus on development.\n\n## Getting Started\n\n* Downloads and install [Wrangler](https://developers.cloudflare.com/workers/cli-wrangler/install-update).\n* Log in to Wrangler with `wrangler login`. AthenaDB **requires** a $5/month Workers subscription to function.\n* Run the following commands:\n\n```bash\ngit clone https://github.com/TimeSurgeLabs/athenadb.git\ncd athenadb\nnpm run create-vector\nnpm run create-db\n```\n\nCopy the output Database ID and paste it in `wrangler.toml` under `database_id` . Then, run the following two commands:\n\n```bash\nnpm run init-db\nnpm run deploy\n```\n\nYou should get an output with your API URL. You can now use the API endpoints.\n\n## API Endpoints\n\n### `POST /:namespace/insert`\n\nInserts text data into the database. Text is converted into embeddings using Cloudflare AI and stored along with a unique identifier.\n* **Request Body**:\n  + `input`: A single string (max 1024 characters).\n  + `inputs`: An array of strings (each max 1024 characters).\n\n### `POST /:namespace/query`\n\nQueries the database for similar text embeddings. Specify `?limit=number` in the URL to specify the number of results to return. The default is 5, the maximum is 20.\n* **Request Body**:\n  + `input`: A single string for querying. (max 1024 characters)\n  + `inputs`: An array of strings for batch querying. (each max 1024 characters)\n\n### `GET /:namespace/:uuid`\n\nRetrieves a specific entry from the database using its unique identifier (UUID). Add query parameters `?vector=true` to retrieve the vector along with the entry. Add query parameters `?db_id=true` to retrieve the SQL table ID along with the entry.\n\n### `GET /:namespace?limit=10\u0026offset=0`\n\nRetrieves all entries from the given namespace. Limit can be set to a maximum of 100 entries. Add query parameters `?vector=true` to retrieve the vectors along with the entries. Add query parameters `?db_id=true` to retrieve the SQL table ID along with the entries.\n\n### `DELETE /:namespace/:uuid`\n\nDeletes a specific entry from the database using its unique identifier (UUID). **Warning**: This action is irreversible.\n\n### `DELETE /:namespace`\n\nDeletes all entries from the given namespace. **Warning**: This action is irreversible.\n\n### `POST /embeddings`\n\nGenerates embeddings for given text without storing it in the database.\n* **Request Body**:\n  + `text`: A string whose embedding is to be generated.\n\n### `GET /`\n\nA test endpoint that returns 'Hello world!' as a response.\n\n## Usage Examples\n\n### Inserting Text\n\n```typescript\nfetch('https://athenadb.yourusername.workers.dev/your-namespace/insert', {\n  method: 'POST',\n  headers: { 'Content-Type': 'application/json' },\n  body: JSON.stringify({ input: 'Your text here' })\n})\n```\n\n### Querying the Database\n\n```typescript\nfetch('https://athenadb.yourusername.workers.dev/your-namespace/query', {\n  method: 'POST',\n  headers: { 'Content-Type': 'application/json' },\n  body: JSON.stringify({ input: 'Query text' })\n})\n```\n\n### Retrieving an Entry\n\n```typescript\nfetch('https://athenadb.yourusername.workers.dev/your-namespace/your-uuid', {\n  method: 'GET'\n})\n```\n\n### Deleting an Entry\n\n```typescript\nfetch('https://athenadb.yourusername.workers.dev/your-namespace/your-uuid', {\n  method: 'DELETE'\n})\n```\n\n### Generating Embeddings\n\n```typescript\nfetch('https://athenadb.yourusername.workers.dev/embeddings', {\n  method: 'POST',\n  headers: { 'Content-Type': 'application/json' },\n  body: JSON.stringify({ text: 'Your text here' })\n})\n```\n\n## Clients\n\n* [Python client](https://gist.github.com/chand1012/f85a87073e709c51a8a75c69151de907)\n","funding_links":[],"categories":["TypeScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTimeSurgeLabs%2Fathenadb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FTimeSurgeLabs%2Fathenadb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FTimeSurgeLabs%2Fathenadb/lists"}