--- updatedAt: 2026-10-19T20:14:11.000Z agentTools: projectIndex: https://docs.skyfire.xyz/llms.txt --- # Create Organization User Buyer Agent As an Organization Admin, create an ungrouped buyer agent for an organization user, with a wallet and one API key. Authenticate with an **Organization Admin User API key**, sent in the `skyfire-api-key` header. Keys belonging to Organization Admins are accepted; a `MEMBER` key, or any Agent API key, is rejected with `401`. The user must belong to your organization and be active: an unknown user returns `404` and a deactivated user returns `400`. ### One ungrouped buyer per user A user holds **at most one** ungrouped buyer agent, and a deactivated one still counts. Most users already have one, created as `Buyer 1` by [Create Organization User](/reference/create-organization-user). This endpoint is for users who were created directly into an agent group and so have no buyer of their own, or whose buyer was never created. If the user already has an ungrouped buyer, the call returns `409`; reactivate or rename the existing agent with [Update Organization User Agent](/reference/update-organization-user-agent) instead. Agents that belong to agent groups do not count toward this limit. A user may be enrolled in any number of groups alongside their own buyer. ### Naming rules `displayName` must be printable ASCII, 1 to 100 characters, with at least one non-space character. Names are compared case-insensitively with whitespace trimmed and collapsed. The name must be free among the user's **active** agents, and may not match an **active agent group** in your organization. Either collision returns `409`. All checks run before anything is provisioned, so a refused request creates nothing. > `apiKey` is returned **only in this response** and cannot be retrieved again. Store it securely before discarding the response. Further keys can be created with [Create Agent API Key](/reference/create-agent-api-key). # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "skyfire-agent-and-token-apis", "version": "1.0" }, "servers": [ { "url": "https://api.skyfire.xyz" } ], "components": { "securitySchemes": { "sec0": { "type": "apiKey", "name": "skyfire-api-key", "in": "header" } } }, "security": [ { "sec0": [] } ], "paths": { "/api/v1/organizations/users/{userId}/agents/buyer": { "post": { "description": "As an Organization Admin, create an ungrouped buyer agent for an organization user, with a wallet and one API key.", "parameters": [ { "in": "path", "name": "userId", "required": true, "schema": { "type": "string", "format": "uuid" }, "description": "Unique identifier of the organization user. e.g. `\"906fc259-ef0a-4736-bdcd-c1d5a78db483\"`" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "displayName": { "type": "string", "minLength": 1, "maxLength": 100, "description": "Display name of the new agent, shown to sellers as `aid.name`. Printable ASCII with at least one non-space character, 1 to 100 characters. Must be free among the user's active agents and not match an active agent group in your organization. e.g. `\"Procurement Agent\"`" } }, "required": [ "displayName" ] }, "examples": { "Create a buyer agent": { "summary": "Create a buyer agent", "value": { "displayName": "Procurement Agent" } } } } } }, "responses": { "200": { "description": "Ok", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "description": "Unique identifier of the created agent." }, "apiKey": { "type": "string", "description": "API key for the agent. Returned only in this response and cannot be retrieved again, store it securely." } }, "required": [ "id", "apiKey" ] }, "examples": { "Ok": { "summary": "Ok", "value": { "id": "b8f3c2a1-6d4e-4f7a-9c0b-2e1d5a8f3c7b", "apiKey": "aff074ee-ea8b-4643-bad1-913a534a5d7a" } } } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "examples": { "User deactivated": { "summary": "User deactivated", "value": { "code": "BAD_REQUEST", "message": "User is not active" } } } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "examples": { "Unauthorized": { "summary": "Unauthorized", "value": { "code": "NOT_AUTHORIZED", "message": "Invalid Organization User API Key" } } } } } }, "404": { "description": "Not Found", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "examples": { "User not in your organization": { "summary": "User not in your organization", "value": { "code": "NOT_FOUND", "message": "User not found" } } } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "examples": { "User already has an ungrouped buyer": { "summary": "User already has an ungrouped buyer", "value": { "code": "CONFLICT", "message": "User already has a buyer agent" } }, "Name used by one of the user's active agents": { "summary": "Name used by one of the user's active agents", "value": { "code": "CONFLICT", "message": "An active agent with this name already exists" } }, "Name reserved by an agent group": { "summary": "Name reserved by an agent group", "value": { "code": "CONFLICT", "message": "This name belongs to an agent group in your organization" } } } } } }, "422": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "examples": { "Unprocessable Entity": { "summary": "Unprocessable Entity", "value": { "code": "VALIDATION_ERROR", "message": "Validation Error", "details": { "displayName": { "message": "Must be printable ASCII with at least one non-space character" } } } } } } } } }, "operationId": "post_api-v1-organizations-users-userid-agents-buyer", "x-readme": { "code-samples": [ { "code": "curl -i -X POST 'https://api.skyfire.xyz/api/v1/organizations/users/906fc259-ef0a-4736-bdcd-c1d5a78db483/agents/buyer' \\\n -H 'skyfire-api-key: ec0bf984-34f9-4e1e-a06e-984f3dfb089e' \\\n -H 'Content-Type: application/json' \\\n -d '{\"displayName\":\"Procurement Agent\"}'", "language": "shell", "name": "cURL" }, { "code": "const res = await fetch(\n 'https://api.skyfire.xyz/api/v1/organizations/users/906fc259-ef0a-4736-bdcd-c1d5a78db483/agents/buyer',\n {\n method: 'POST',\n headers: {\n 'skyfire-api-key': 'ec0bf984-34f9-4e1e-a06e-984f3dfb089e',\n 'Content-Type': 'application/json'\n },\n body: JSON.stringify({ displayName: 'Procurement Agent' })\n }\n);\nconst agent = await res.json();\nconsole.log('store this key now:', agent.apiKey);", "language": "node", "name": "" }, { "code": "import http.client\nimport json\n\nconn = http.client.HTTPSConnection(\"api.skyfire.xyz\")\nheaders = {\n 'skyfire-api-key': 'ec0bf984-34f9-4e1e-a06e-984f3dfb089e',\n 'Content-Type': 'application/json'\n}\npayload = json.dumps({\"displayName\": \"Procurement Agent\"})\nconn.request(\"POST\", \"/api/v1/organizations/users/906fc259-ef0a-4736-bdcd-c1d5a78db483/agents/buyer\", payload, headers)\nres = conn.getresponse()\nprint(res.read().decode(\"utf-8\"))", "language": "python", "name": "" } ], "samples-languages": [ "shell", "node", "python" ] }, "summary": "Create Organization User Buyer Agent" } } }, "x-readme": { "headers": [ { "key": "skyfire-api-key", "value": "" } ], "explorer-enabled": false, "proxy-enabled": false }, "x-readme-fauxas": true } ```