> ## Documentation Index
> Fetch the complete documentation index at: https://docs.asteragents.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create bulk invitations
> Send invitations to multiple email addresses in a single request.
**Smart invitation handling:**
- If the email already has a Clerk account: Adds them directly as a member (no email sent)
- If the email is already a member: Returns success without error (idempotent)
- If the email is new: Sends an invitation email
Invitations expire after 30 days and can be revoked using `DELETE /admin/invitations`.
## OpenAPI
````yaml /openapi.yaml post /admin/invitations
openapi: 3.1.0
info:
title: AsterAgents API
version: 1.0.0
description: >
API for AsterAgents platform operations.
- **Admin endpoints** (`/admin/*`) require organization admin privileges
(`org:admin` role)
- **Agent endpoints** (`/agents`) require agent management permissions or
`org:admin` role
- **Knowledge base endpoints** (`/kb/*`) require standard authentication
- **Skills endpoints** (`/skills/*`) require standard authentication
- **File endpoints** (`/upload/*`, `/kb/files`, `/skills/files`) require
standard authentication
contact:
name: AsterAgents Support
url: https://asteragents.com/support
servers:
- url: https://asteragents.com/api
description: Production
- url: http://localhost:3000/api
description: Local development
security:
- bearerAuth: []
tags:
- name: Users
description: Manage active organization users
- name: Invitations
description: Manage organization invitations
- name: Files
description: Upload and manage files
- name: Knowledge Bases
description: Manage knowledge bases and their files
- name: Knowledge Base Management
description: Create, update, and delete knowledge bases
- name: Agents
description: Create, update, and delete agents
- name: Agent Tags
description: Organize agents with tags
- name: Tools
description: Discover the tool catalog available to your organization
- name: Skills
description: Manage agent skills
- name: Skill Files
description: Manage bundled files for skills
- name: Conversations
description: Invoke agents and retrieve conversation history and messages
- name: Scheduled Tasks
description: Schedule agents to run automatically on a cron schedule
paths:
/admin/invitations:
post:
tags:
- Invitations
summary: Create bulk invitations
description: >
Send invitations to multiple email addresses in a single request.
**Smart invitation handling:**
- If the email already has a Clerk account: Adds them directly as a
member (no email sent)
- If the email is already a member: Returns success without error
(idempotent)
- If the email is new: Sends an invitation email
Invitations expire after 30 days and can be revoked using `DELETE /admin/invitations`.
operationId: createInvitations
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- invitations
properties:
invitations:
type: array
description: Array of invitations to send
minItems: 1
maxItems: 50
items:
type: object
required:
- email
properties:
email:
type: string
format: email
description: Email address to invite
role:
type: string
default: org:member
enum:
- org:admin
- org:member
description: Role to assign when user accepts
metadata:
type: object
description: Custom metadata applied when user accepts
additionalProperties: true
examples:
simple:
summary: Simple invitations
value:
invitations:
- email: user1@company.com
- email: user2@company.com
withMetadata:
summary: Invitations with metadata and role
value:
invitations:
- email: engineer@company.com
role: org:member
metadata:
department: engineering
title: Software Engineer
- email: admin@company.com
role: org:admin
responses:
'200':
description: All invitations sent successfully
content:
application/json:
schema:
type: object
required:
- success
- total
- successful
- failed
- results
properties:
success:
type: boolean
total:
type: integer
successful:
type: integer
failed:
type: integer
results:
type: array
items:
oneOf:
- $ref: '#/components/schemas/InvitationResult'
- $ref: '#/components/schemas/DirectMembershipResult'
errors:
type: array
items:
$ref: '#/components/schemas/InvitationError'
examples:
allSuccess:
value:
success: true
total: 2
successful: 2
failed: 0
results:
- email: newuser@company.com
success: true
invitationId: orginv_2ABC123DEF
status: pending
type: invitation
metadata: {}
- email: existinguser@company.com
success: true
userId: user_2XYZ789GHI
membershipId: orgmem_2MNO456PQR
status: active
type: direct_membership
metadata: {}
'207':
description: Partial success
content:
application/json:
schema:
type: object
required:
- success
- total
- successful
- failed
- results
- errors
properties:
success:
type: boolean
total:
type: integer
successful:
type: integer
failed:
type: integer
results:
type: array
items:
$ref: '#/components/schemas/InvitationResult'
errors:
type: array
items:
$ref: '#/components/schemas/InvitationError'
'400':
description: Bad request - invalid email or parameters
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
invalidEmail:
summary: Invalid email address
value:
error: Invalid request data
details:
- message: Invalid email address
path:
- invitations
- 0
- email
'403':
$ref: '#/components/responses/Forbidden'
'500':
$ref: '#/components/responses/InternalServerError'
components:
schemas:
InvitationResult:
type: object
required:
- email
- success
- invitationId
- status
- type
properties:
email:
type: string
format: email
success:
type: boolean
example: true
invitationId:
type: string
example: orginv_2ABC123DEF
status:
type: string
example: pending
type:
type: string
enum:
- invitation
example: invitation
metadata:
type: object
additionalProperties: true
DirectMembershipResult:
type: object
required:
- email
- success
- userId
- membershipId
- status
- type
properties:
email:
type: string
format: email
success:
type: boolean
example: true
userId:
type: string
example: user_2ABC123DEF
membershipId:
type: string
example: orgmem_2XYZ789GHI
status:
type: string
enum:
- active
- already_member
example: active
type:
type: string
enum:
- direct_membership
- existing_membership
example: direct_membership
metadata:
type: object
additionalProperties: true
InvitationError:
type: object
required:
- email
- success
- error
properties:
email:
type: string
format: email
success:
type: boolean
example: false
error:
type: string
example: Invalid email address
Error:
type: object
required:
- error
properties:
error:
type: string
example: Bad Request
details:
type: array
items:
type: object
additionalProperties: true
responses:
Forbidden:
description: Forbidden - User is not an admin in the organization
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: 'Unauthorized: User is not an admin in this organization'
InternalServerError:
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
example:
error: Internal Server Error
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: |
JWT token from Clerk authentication.
Must be from a user with `org:admin` role.
````