@arke-institute/sdk 3.6.4 → 3.6.6

package/openapi/spec.json

@@ -116,13 +116,13 @@
         "type": "http",
         "scheme": "bearer",
         "bearerFormat": "JWT",
-        "description": "Supabase JWT token"
+        "description": "Supabase JWT token. Use `Authorization: Bearer <jwt>`. Only for JWT tokens from Supabase auth - do NOT use Bearer with API keys."
       },
       "apiKeyAuth": {
         "type": "apiKey",
         "in": "header",
         "name": "Authorization",
-        "description": "API Key authentication. Format: `ApiKey ak_xxx` (agent) or `ApiKey uk_xxx` (user)"
+        "description": "API Key authentication. **Important:** Use `Authorization: ApiKey <key>` (NOT Bearer). Format: `ApiKey uk_xxx` (user keys) or `ApiKey ak_xxx` (agent keys). Using Bearer with API keys will fail."
       }
     },
     "parameters": {
@@ -1120,6 +1120,12 @@
             "format": "uri",
             "description": "URL for collection display image"
           },
+          "use_roles_default": {
+            "type": "boolean",
+            "default": true,
+            "description": "Whether to merge with default roles (true) or use only provided roles (false). Public role with *:view is always ensured.",
+            "example": true
+          },
           "roles": {
             "type": "object",
             "additionalProperties": {
@@ -1128,26 +1134,11 @@
                 "type": "string"
               }
             },
-            "description": "Custom role definitions (defaults to owner/editor/viewer/public)",
+            "description": "Role definitions. When use_roles_default is true (default), these merge with defaults. When false, these replace defaults entirely.",
             "example": {
-              "captain": [
-                "*:view",
-                "*:update",
-                "*:create",
-                "collection:manage"
-              ],
-              "harpooner": [
-                "*:view",
-                "*:update",
-                "*:create"
-              ],
-              "crew": [
-                "*:view",
-                "entity:create"
-              ],
               "public": [
-                "entity:view",
-                "collection:view"
+                "*:view",
+                "*:invoke"
               ]
             }
           },
@@ -2258,6 +2249,11 @@
             "pattern": "^(?:II[0-9A-HJKMNP-TV-Z]{24}|[FC][0-9A-HJKMNP-TV-Z]{25}|[0-9A-HJKMNP-TV-Z]{26})$",
             "description": "Parent collection ID (creates collection relationship)",
             "example": "01KDETYWYWM0MJVKM8DK3AEXPY"
+          },
+          "sync_index": {
+            "type": "boolean",
+            "default": false,
+            "description": "Wait for collection index update before returning. Use when checking for duplicates immediately after creation. Adds ~1-5ms latency per collection."
           }
         },
         "required": [
@@ -8401,6 +8397,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "responses": {
@@ -8479,6 +8478,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "responses": {
@@ -8717,6 +8719,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "responses": {
@@ -8763,6 +8768,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "requestBody": {
@@ -8813,6 +8821,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "responses": {
@@ -8856,6 +8867,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -9029,6 +9043,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "requestBody": {
@@ -9100,13 +9117,16 @@
           "Collections"
         ],
         "summary": "Create a new collection",
-        "description": "Creates a collection with the authenticated user as owner.\n\n---\n**Permission:** `collection:create`  \n**Auth:** required",
+        "description": "Creates a collection with the authenticated user as owner.\n\n**Default Roles:**\n\nBy default (`use_roles_default: true`), collections include these standard roles:\n- `owner`: Full control including collection management\n- `editor`: Can modify entities but not collection settings\n- `viewer`: Read-only access\n- `public`: Public read access (`*:view`)\n\n**Customizing Roles:**\n\nPass custom `roles` to override specific defaults while keeping others. For example, to make entities publicly invokable (for agents):\n```json\n{ \"roles\": { \"public\": [\"*:view\", \"*:invoke\"] } }\n```\n\nSet `use_roles_default: false` to define all roles from scratch.\n\n**Platform Requirement:** The `public` role with `*:view` is always automatically ensured, guaranteeing all collections are publicly readable.\n\n---\n**Permission:** `collection:create`  \n**Auth:** required",
         "x-arke-action": "collection:create",
         "x-arke-auth": "required",
         "x-arke-tier": "standard",
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "requestBody": {
@@ -9257,6 +9277,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -9403,6 +9426,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -9518,6 +9544,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -9643,6 +9672,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -9813,6 +9845,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -9928,6 +9963,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -10057,6 +10095,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -10182,7 +10223,7 @@
           "Collections"
         ],
         "summary": "List entities in a collection",
-        "description": "Returns entities belonging to this collection from the graph database.\n\nSupports pagination and optional type filtering. Results are ordered by creation date (newest first).\n\n**Expansion Modes:**\n\nBy default, returns lightweight summaries from GraphDB (pi, type, label, timestamps).\n\nUse the `expand` parameter to hydrate entity data from storage:\n\n- **`?expand=preview`**: Adds `preview` field with fresh lightweight data (label, truncated description/text, timestamps). ~5-10KB per entity.\n\n- **`?expand=full`**: Adds `entity` field with complete manifest (all properties, relationships, version history). ~20-50KB per entity.\n\n**Performance Note:** Expansion requires fetching each entity from storage. Limited to 100 entities per request. Use smaller `limit` values when expanding.\n\n---\n**Permission:** `collection:view`  \n**Auth:** optional",
+        "description": "Returns entities belonging to this collection.\n\nSupports pagination and optional type filtering. Results are ordered by creation date (newest first).\n\n**Expansion Modes:**\n\nBy default, returns lightweight summaries (pi, type, label, timestamps).\n\nUse the `expand` parameter to hydrate entity data from storage:\n\n- **`?expand=preview`**: Adds `preview` field with fresh lightweight data (label, truncated description/text, timestamps). ~5-10KB per entity.\n\n- **`?expand=full`**: Adds `entity` field with complete manifest (all properties, relationships, version history). ~20-50KB per entity.\n\n**Performance Note:** Expansion requires fetching each entity from storage. Limited to 100 entities per request. Use smaller `limit` values when expanding.\n\n---\n**Permission:** `collection:view`  \n**Auth:** optional",
         "x-arke-action": "collection:view",
         "x-arke-auth": "optional",
         "x-arke-tier": "external",
@@ -10288,7 +10329,7 @@
             }
           },
           "503": {
-            "description": "GraphDB service unavailable"
+            "description": "Collection index service unavailable"
           }
         }
       }
@@ -10507,6 +10548,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -10629,6 +10673,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -10885,6 +10932,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -11029,6 +11079,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -11279,6 +11332,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -11412,6 +11468,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -11849,6 +11908,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -11931,6 +11993,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -12168,6 +12233,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -12321,6 +12389,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -12453,6 +12524,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -12568,6 +12642,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -12701,6 +12778,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "requestBody": {
@@ -12977,6 +13057,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "requestBody": {
@@ -13140,6 +13223,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -13272,6 +13358,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -13397,6 +13486,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -13522,6 +13614,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -13647,6 +13742,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -13760,6 +13858,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -13842,6 +13943,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -13929,6 +14033,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "requestBody": {
@@ -14092,6 +14199,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -14224,6 +14334,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -14409,6 +14522,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -14596,6 +14712,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -14675,6 +14794,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -14754,6 +14876,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "parameters": [
@@ -14825,6 +14950,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "requestBody": {
@@ -14887,6 +15015,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "requestBody": {
@@ -15092,6 +15223,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "requestBody": {
@@ -15335,6 +15469,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "requestBody": {
@@ -15529,6 +15666,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "requestBody": {
@@ -15730,6 +15870,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "requestBody": {
@@ -15958,6 +16101,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "requestBody": {
@@ -16175,6 +16321,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "requestBody": {
@@ -16260,6 +16409,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "responses": {
@@ -16302,6 +16454,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "responses": {
@@ -16368,6 +16523,9 @@
         "security": [
           {
             "bearerAuth": []
+          },
+          {
+            "apiKeyAuth": []
           }
         ],
         "responses": {

package/openapi/version.json

@@ -1,7 +1,7 @@
 {
   "specVersion": "1.0.0",
   "apiVersion": "1.0.0",
-  "fetchedAt": "2026-02-11T22:34:09.655Z",
+  "fetchedAt": "2026-02-13T15:33:38.555Z",
   "sourceUrl": "https://api.arke.institute/openapi.json",
   "openApiVersion": "3.1.0"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arke-institute/sdk",
-  "version": "3.6.4",
+  "version": "3.6.6",
   "description": "TypeScript SDK for the Arke API - auto-generated from OpenAPI spec",
   "type": "module",
   "main": "dist/index.cjs",