Overview
Profiles are the core identity system in Aya. Each profile has a unique slug and can be of type individual, organization, or product.
List Profiles
List profiles by kind with pagination support.
Locale code (e.g., en, fr, ja)
Comma-separated profile kinds: individual, organization, product
Number of profiles per page
Number of profiles to skip
curl "http://localhost:8080/en/profiles?filter_kind=individual,organization&limit=10"
{
"data": [
{
"id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
"slug": "john-doe",
"kind": "individual",
"title": "John Doe",
"description": "Software Engineer",
"profile_picture_uri": "https://avatars.githubusercontent.com/u/12345",
"locale_code": "en",
"default_locale": "en",
"points": 150,
"created_at": "2024-01-15T10:30:00Z"
}
],
"cursor": {
"next": "eyJvZmZzZXQiOjEwfQ==",
"has_more": true
}
}
Get Profile by Slug
GET /{locale}/profiles/{slug}
Profile slug (e.g., john-doe)
curl "http://localhost:8080/en/profiles/john-doe"
{
"data": {
"id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
"slug": "john-doe",
"kind": "individual",
"title": "John Doe",
"description": "Open source developer",
"profile_picture_uri": "https://avatars.githubusercontent.com/u/12345",
"pronouns": "he/him",
"locale_code": "en",
"default_locale": "en",
"points": 150,
"feature_relations": "public",
"feature_links": "public",
"feature_qa": "disabled",
"feature_discussions": "public",
"option_story_discussions_by_default": true,
"created_at": "2024-01-15T10:30:00Z"
}
}
Check Slug Availability
GET /{locale}/profiles/{slug}/_check
Include soft-deleted profiles in availability check
curl "http://localhost:8080/en/profiles/john-doe/_check"
{
"data": {
"available": false,
"message": "This slug is already taken",
"severity": "error"
}
}
Whether the slug is available
Human-readable availability message
Message severity: info, warning, error
Create Profile
POST /{locale}/profiles/_create
Authentication RequiredThis endpoint requires a valid JWT token in the Authorization header.
Unique slug (2-50 characters, lowercase letters, numbers, hyphens)
Profile kind: individual, organization, product
Profile title (max 100 characters)
Profile description (max 500 characters)
Individual Profile RestrictionEach user can only create ONE individual profile. Organizations and products have no limit.
curl -X POST "http://localhost:8080/en/profiles/_create" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"slug": "my-startup",
"kind": "organization",
"title": "My Startup",
"description": "Building the future of X"
}'
{
"data": {
"id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
"slug": "my-startup",
"kind": "organization",
"title": "My Startup",
"description": "Building the future of X",
"locale_code": "en",
"default_locale": "en",
"points": 0,
"created_at": "2024-03-07T10:30:00Z"
}
}
Update Profile
PATCH /{locale}/profiles/{slug}
Pronouns (e.g., he/him, she/her, they/them)
Custom profile properties (JSON object)
Relations module visibility: public, hidden, disabled
Links module visibility: public, hidden, disabled
Q&A module visibility: public, hidden, disabled
Discussions module visibility: public, hidden, disabled
option_story_discussions_by_default
Enable discussions by default for new stories
curl -X PATCH "http://localhost:8080/en/profiles/john-doe" \
-H "Authorization: Bearer YOUR_JWT_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"pronouns": "he/him",
"feature_discussions": "public",
"option_story_discussions_by_default": true
}'
Check Permissions
GET /{locale}/profiles/{slug}/_permissions
curl "http://localhost:8080/en/profiles/john-doe/_permissions" \
-H "Authorization: Bearer YOUR_JWT_TOKEN"
{
"data": {
"can_edit": true,
"viewer_membership_kind": "owner"
}
}
Whether the user can edit this profile
User’s membership level: follower, sponsor, member, contributor, maintainer, lead, owner
Profile Links
List Profile Links
GET /{locale}/profiles/{slug}/links
{
"data": [
{
"id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
"kind": "github",
"order": 1,
"public_id": "johndoe",
"uri": "https://github.com/johndoe",
"title": "GitHub",
"icon": "github",
"is_verified": true,
"is_featured": true,
"visibility": "public"
}
]
}
Create Profile Link
POST /{locale}/profiles/{slug}/_links
Link kind: website, github, x, linkedin, instagram, youtube, bsky, discord, telegram, external-site
Link URL (required for most kinds)
Link group for organization
Visibility: public, followers, sponsors, members, contributors, maintainers, leads, owners
Profile Pages
List Profile Pages
GET /{locale}/profiles/{slug}/pages
{
"data": [
{
"id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
"slug": "about",
"title": "About Us",
"summary": "Learn more about our mission",
"visibility": "public"
}
]
}
Get Page by Slug
GET /{locale}/profiles/{slug}/pages/{pageSlug}
{
"data": {
"id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
"slug": "about",
"title": "About Us",
"summary": "Learn more about our mission",
"content": "# About\n\nWe are building...",
"visibility": "public",
"published_at": "2024-01-15T10:30:00Z"
}
}
Create Profile Page
POST /{locale}/profiles/{slug}/_pages
Authentication Required - Requires maintainer+ access
Page slug (2-100 characters, lowercase, numbers, hyphens)
Page title (max 200 characters)
Page visibility: public, unlisted, private
Publication timestamp (ISO 8601)
Profile Stories
List Published Stories
GET /{locale}/profiles/{slug}/stories
Number of stories per page
Number of stories to skip
List Authored Stories
GET /{locale}/profiles/{slug}/stories-authored
Profile Relationships
List Contributions
GET /{locale}/profiles/{slug}/contributions
List Members
GET /{locale}/profiles/{slug}/members
