Fill the Organization
Create the project and add the people Valmar can contact — through the Admin UI or programmatically.
Before Valmar can do anything useful, the organization needs a project and some people. There are two paths: the Admin UI (best for a one-time setup or for an operator with a spreadsheet) and the admin REST API (best for seed scripts or repeatable provisioning).
Use the Admin UI when an operator is setting up a workspace by hand.
Create the project
Use the getting-started flow or New Project in the Admin UI to create the project that will own credentials and context requests.
Open the People page
Select the organization in the Admin UI, then open the People page. This is the primary operator surface for adding, editing, and removing people.
Add one person manually
Use Add Person for one-off entries. The form supports name, email, title, timezone, and a short description of what that person usually knows.
Import many people from CSV
Use Import People when you already have a spreadsheet or export. The
CSV input accepts rows in the shape email, name, title, timezone.
Assign people to the project
Open Project Settings and add the relevant people. Enable Project admin when they should administer the project in Admin UI and Project expert when Valmar may route the project's questions to them. A person may have both roles.
What makes a good person profile
- A real work email that Valmar is allowed to contact.
- A clear display name and job title.
- A correct timezone so outreach timing is sensible.
- A short description that says what context this person usually knows.
When the UI path is best
Use the UI when you are setting up one organization by hand, checking imported people, or deciding project membership interactively with an operator.
Use the code path when you want repeatable seed scripts, demo setup, or fixtures.
What's available today
- In simple mode, the system administrator creates local users with passwords from Admin UI People management.
- Bulk profile import is reserved for development fixtures using
VALMAR_AUTH_MODE=dev_headers. - Project creation is available over
POST /api/organizations/{organization_id}/projects. - Project membership assignment is available over
POST /api/projects/{project_id}/people. - People import and project creation require org-admin rights. Membership assignment requires project-admin rights.
Authentication in these examples
The Python REST examples use /api/auth/login, which is available in
username/password deployments. The TypeScript examples assume an operator is
already signed in through the Admin UI. For managed authentication, use the
equivalent authenticated admin session supplied by your identity provider.
Set VALMAR_USERNAME and VALMAR_PASSWORD for the Python examples.
For deployed simple authentication, create people and their credentials from the People page. This keeps password entry and audit events in the system-admin workflow. Clerk deployments continue to manage identity creation in Clerk.
Create a project over HTTP
This setup endpoint is part of the backend REST API. It is not exposed through the public SDKs today, so use direct HTTP from an authenticated operator/admin session.
import os
import httpx
base_url = os.environ["VALMAR_BASE_URL"]
organization_id = os.environ["VALMAR_ORGANIZATION_ID"]
with httpx.Client(base_url=base_url) as client:
login = client.post(
"/api/auth/login",
json={
"username": os.environ["VALMAR_USERNAME"],
"password": os.environ["VALMAR_PASSWORD"],
},
)
login.raise_for_status()
project = client.post(
f"/api/organizations/{organization_id}/projects",
json={
"name": "Support Assistant",
"slug": "support-assistant",
"description_md": "Handles support escalations and missing policy answers.",
},
)
project.raise_for_status()
print(project.json()["id"])const organizationId = "your-org-id";
// Assumes this runs inside an already-authenticated operator web app.
const project = await fetch(`/api/organizations/${organizationId}/projects`, {
method: "POST",
headers: { "Content-Type": "application/json" },
credentials: "include",
body: JSON.stringify({
name: "Support Assistant",
slug: "support-assistant",
description_md: "Handles support escalations and missing policy answers.",
}),
});
if (!project.ok) throw new Error(await project.text());
console.log((await project.json()).id);Assign a person to the project
Once the project and the organization-level people exist, add project
memberships over the project people API. The independent is_project_admin
and is_project_expert flags may each be true, and at least one is required.
import os
import httpx
base_url = os.environ["VALMAR_BASE_URL"]
project_id = os.environ["VALMAR_PROJECT_ID"]
member_id = os.environ["VALMAR_MEMBER_ID"]
with httpx.Client(base_url=base_url) as client:
login = client.post(
"/api/auth/login",
json={
"username": os.environ["VALMAR_USERNAME"],
"password": os.environ["VALMAR_PASSWORD"],
},
)
login.raise_for_status()
membership = client.post(
f"/api/projects/{project_id}/people",
json={
"member_id": member_id,
"is_project_admin": False,
"is_project_expert": True,
},
)
membership.raise_for_status()
print(membership.json()["id"])const projectId = "your-project-id";
const memberId = "your-member-id";
// Assumes this runs inside an already-authenticated operator web app.
const membership = await fetch(`/api/projects/${projectId}/people`, {
method: "POST",
headers: { "Content-Type": "application/json" },
credentials: "include",
body: JSON.stringify({
member_id: memberId,
is_project_admin: false,
is_project_expert: true,
}),
});
if (!membership.ok) throw new Error(await membership.text());
console.log((await membership.json()).id);Auth model
These setup endpoints use admin-style authorization, not the normal runtime integration flow. A project API key is suitable for search, gather, and MCP. For organization and project provisioning, use an authenticated operator/admin session or internal admin automation.
Next
Continue to Quickstart to run the first search-and-gather loop end to end.