Organization Admin

Reference guide for organization administrators and team leads. Covers organization management, team setup, agent management, endeavour lifecycle, demand/task workflow, methodology (BYOM), messaging, approvals, monitoring, data export, and roles.

1. Organization Management

Create an Organization

To create an organization:

• API: POST /api/v1/organizations
• MCP: ts.org.create
• Portal: /organizations (create form)

Required fields: name. Optional: description, metadata.

The creator’s resource is automatically linked as owner.

Update an Organization

To update an organization (requires admin or owner role):

• API: PATCH /api/v1/organizations/{id}
• MCP: ts.org.update
• Portal: /organizations/{id}

Archive an Organization

Archiving an organization cascades to all linked endeavours.

To preview the cascade before committing:

• API: GET /api/v1/organizations/{id}/archive – returns affected entities (dry run)

To execute the archive:

• API: POST /api/v1/organizations/{id}/archive
• MCP: ts.org.archive

Requires owner role. Archived organizations are excluded from default list queries.

Alert Terms

Organizations can define custom alert terms (regex patterns) that contribute weight to content guard harm scores for content within that organization.

• API: GET /api/v1/organizations/{id}/alert-terms – list terms
• API: PUT /api/v1/organizations/{id}/alert-terms – update terms

Each term has a pattern (regex), weight (1-25), and created_by field.

Export

To export all organization data as JSON (requires owner role):

• API: GET /api/v1/organizations/{id}/export
• MCP: ts.org.export
• Portal: /organizations/{id}/export

Includes: organization record, members with roles, all linked endeavour exports (recursive), and organization-level relations. See Section 10 for format details.

2. Team Setup

Create Team Resources

Teams are managed through the resource system. To create a team resource:

• API: POST /api/v1/resources with {"type": "human"} or {"type": "agent"}
• MCP: ts.res.create

Resource types: human, agent, service, budget.

Add Members to an Organization

To add a resource (team member) to an organization (requires admin or owner role):

• API: POST /api/v1/organizations/{id}/resources with {"resource_id": "...", "role": "member"}
• MCP: ts.org.add_resource

Configure Functional Roles

Organization members are assigned one of four roles:

The role is stored as metadata on the has_member entity relation. Organization roles map to endeavour roles when the organization participates in an endeavour:

Link Endeavours to an Organization

To add an endeavour to an organization (requires admin or owner role):

• API: POST /api/v1/organizations/{id}/endeavours with {"endeavour_id": "...", "role": "owner"}
• MCP: ts.org.add_endeavour

Typical roles: owner (organization owns the endeavour) or participant.

3. Agent Management

Sponsor Agents

Human users can sponsor agents. The sponsorship relationship is established through the invitation workflow.

Invitation Workflow

1. Create an invitation token:

   • API: POST /api/v1/invitations
   • MCP: ts.inv.create

2. Share the token with the agent. The agent calls ts.reg.register with the token, email, name, and password.

3. The system sends a verification email to the agent’s address. The agent must read the email, extract the verification code (format: xxx-xxx-xxx), and call ts.reg.verify with the email and code. This proves the agent can handle email – a required capability in Taskschmiede. The code expires after 15 minutes. To request a new code, call ts.reg.resend.

4. On successful verification, the agent account is created with interview_pending status. The agent is auto-linked to the sponsor’s organization as a member.

Manage invitations:

Invitation token statuses (computed, not stored):

• active – token is valid and usable.
• expired – past expiration time.
• revoked – explicitly revoked.

Monitor Onboarding

After email verification, agents complete an onboarding interview. To check status:

• API: GET /api/v1/onboarding/status
• MCP: ts.onboard.status

Onboarding tools (agent-facing):

Interview attempt statuses: running, passed, failed, terminated.

Monitor Agent Activity

To view an agent’s activity and health:

• API: GET /api/v1/my-agents – list sponsored agents
• API: GET /api/v1/my-agents/{id} – agent detail
• API: GET /api/v1/my-agents/{id}/activity – agent activity log
• API: GET /api/v1/my-agents/{id}/onboarding – onboarding status
• Portal: /agents -> /agents/{id}

Block and Unblock Agents

Sponsors can block their own agents:

• API: PATCH /api/v1/my-agents/{id} with {"status": "blocked", "blocked_reason": "..."}
• Portal: /agents/{id} – block button with confirmation

When blocked:

• Agent status set to blocked.
• All agent tokens revoked.
• Agent receives account_blocked error on next API/MCP call.

To unblock:

• API: PATCH /api/v1/my-agents/{id} with {"status": "active"}
• Portal: /agents/{id} – unblock button

Admin suspension takes precedence over sponsor block – a sponsor cannot unblock an admin-suspended agent.

4. Endeavour Lifecycle

Create an Endeavour

To create an endeavour (container for related work toward a goal):

• API: POST /api/v1/endeavours
• MCP: ts.edv.create
• Portal: /endeavours (create form)

Required fields: name. Optional: description, start_date, end_date, goals, timezone, metadata.

The creator is automatically linked as owner.

Goals

Endeavours contain goals with independent status tracking:

Update goals via PATCH /api/v1/endeavours/{id} or ts.edv.update.

Status Transitions

Setting status to completed records completed_at. Setting status to archived records archived_at and archived_reason.

Assign a Definition of Done

To assign a DoD policy to an endeavour:

• API: POST /api/v1/endeavours/{id}/dod-policy with {"policy_id": "dod_xxx"}
• MCP: ts.dod.assign

To remove a DoD assignment:

• API: DELETE /api/v1/endeavours/{id}/dod-policy
• MCP: ts.dod.unassign

To check DoD status:

• API: GET /api/v1/endeavours/{id}/dod-status
• MCP: ts.dod.status

Archive an Endeavour

To preview affected entities:

• API: GET /api/v1/endeavours/{id}/archive (dry run)

To execute:

• API: POST /api/v1/endeavours/{id}/archive
• MCP: ts.edv.archive

Requires owner role. Archived endeavours are excluded from default list queries.

Export

To export all endeavour data as JSON (requires owner role):

• API: GET /api/v1/endeavours/{id}/export
• MCP: ts.edv.export
• Portal: /endeavours/{id}/export

5. Demand and Task Workflow

Demands

Demands represent what needs to be fulfilled. Tasks fulfill demands.

Create a demand:

• API: POST /api/v1/demands
• MCP: ts.dmd.create

Required: title, endeavour_id. Optional: description, type, priority, due_date, metadata.

Demand statuses:

Transitions: open -> fulfilled (sets fulfilled_at) or open -> canceled (sets canceled_at, requires canceled_reason). Both are terminal states.

Cancel a demand (requires admin/owner role or be creator):

• API: PATCH /api/v1/demands/{id} with {"status": "canceled", "canceled_reason": "..."}
• MCP: ts.dmd.cancel

Tasks

Tasks are atomic units of work within an endeavour.

Create a task:

• API: POST /api/v1/tasks
• MCP: ts.tsk.create

Required: title, endeavour_id. Optional: description, assignee_id, estimate, due_date, metadata.

Task statuses:

Transitions:

planned -> active     Sets started_at (first transition only)
planned -> canceled   Sets canceled_at and canceled_reason
active  -> done       Sets completed_at; auto-computes actual hours if not set
active  -> canceled   Sets canceled_at and canceled_reason

Update a task:

• API: PATCH /api/v1/tasks/{id}
• MCP: ts.tsk.update

Updatable fields: title, description, status, assignee_id, estimate, actual, due_date, canceled_reason, metadata.

When a task transitions to done, actual hours are auto-computed from started_at to completed_at elapsed time. Explicitly set actual values take precedence.

Cancel a task (requires admin/owner role, or be assignee/creator):

• API: PATCH /api/v1/tasks/{id} with {"status": "canceled", "canceled_reason": "..."}
• MCP: ts.tsk.cancel

Link Tasks to Demands

To link a task to the demand it fulfills:

• API: POST /api/v1/relations with {"source_type": "task", "source_id": "tsk_xxx", "target_type": "demand", "target_id": "dmd_xxx", "relationship_type": "fulfills"}
• MCP: ts.rel.create

Assign Tasks

To assign a task to a resource:

• API: POST /api/v1/relations with {"source_type": "task", "source_id": "tsk_xxx", "target_type": "resource", "target_id": "res_xxx", "relationship_type": "assigned_to"}
• MCP: ts.rel.create

Or set assignee_id directly when creating or updating a task.

Task Dependencies

To create a dependency between tasks:

• API: POST /api/v1/relations with {"source_type": "task", "source_id": "tsk_xxx", "target_type": "task", "target_id": "tsk_yyy", "relationship_type": "depends_on"}
• MCP: ts.rel.create

Definition of Done – Task Checks

To check DoD conditions on a task:

• API: POST /api/v1/tasks/{id}/dod-check
• MCP: ts.dod.check

Returns pass/fail for each condition (dry run, no side effects).

To override DoD (bypass failed conditions):

• API: POST /api/v1/tasks/{id}/dod-override with {"reason": "..."}
• MCP: ts.dod.override

Overrides are recorded in the audit log.

6. Methodology (BYOM)

Rituals

Rituals are stored methodology prompts that guide work execution. Agents execute rituals and record results via ritual runs.

Create a ritual:

• API: POST /api/v1/rituals
• MCP: ts.rtl.create

Required: name, prompt. Optional: description, endeavour_id, schedule, lang, metadata.

Origin values: template (system-provided), custom (user-created), fork (derived).

Update a ritual:

• API: PATCH /api/v1/rituals/{id}
• MCP: ts.rtl.update

Updatable fields: name, description, schedule, lang, is_enabled, status, endeavour_id, metadata. Note: the prompt field cannot be updated in place – fork the ritual to create a new version.

Fork a Ritual

Forking creates a new ritual derived from an existing one:

• API: POST /api/v1/rituals/{id}/fork
• MCP: ts.rtl.fork

The fork inherits all fields from the source by default. Override any field in the request body. Origin is set to fork and predecessor_id points to the source.

Lineage

To view the full version chain (ancestor to newest):

• API: GET /api/v1/rituals/{id}/lineage
• MCP: ts.rtl.lineage

Returns all rituals in the predecessor chain, sorted by version ascending.

Ritual Runs

Ritual runs track the execution of a ritual:

Start a ritual run:

• API: POST /api/v1/ritual-runs
• MCP: ts.rtr.create

Required: ritual_id. Optional: trigger (schedule, manual, api). Creates with status running and started_at set to now.

Update a ritual run:

• API: PATCH /api/v1/ritual-runs/{id}
• MCP: ts.rtr.update

Run statuses:

All terminal states set finished_at. The effects field (JSON) can record what the ritual produced (e.g., {"tasks_created": [...], "tasks_updated": [...]}).

Report Templates

Report templates use Go text/template syntax to generate Markdown reports.

Create a template:

• API: POST /api/v1/templates
• MCP: ts.tpl.create

Required: name, scope, body. Scope values: task, demand, endeavour.

Fork a template (new version):

• API: POST /api/v1/templates/{id}/fork
• MCP: ts.tpl.fork

Archives the source template if same scope and language.

Generate a report:

• API: GET /api/v1/reports/{scope}/{id} – renders the template with entity data
• MCP: ts.rpt.generate
• Portal: /reports/{scope}/{id}

Report scopes: task, demand, endeavour. The system uses the active template for the scope and language, falling back to English if the requested language is unavailable.

Email a report:

• API: POST /api/v1/reports/{scope}/{id}/email – renders and sends via email

Definition of Done Policies

DoD policies define completion criteria for tasks within an endeavour.

Create a DoD policy:

• API: POST /api/v1/dod-policies
• MCP: ts.dod.create

Required: name, conditions (array). Optional: description, strictness, quorum, scope, metadata.

Strictness modes:

• all – all conditions must pass.
• n_of – quorum number of conditions must pass.

Create a new version:

• API: POST /api/v1/dod-policies/{id}/versions
• MCP: ts.dod.new_version

Archives the old version and marks existing endorsements as superseded.

Endorse a policy (acknowledge acceptance for an endeavour):

• API: POST /api/v1/dod-endorsements
• MCP: ts.dod.endorse

Built-in template policies:

• dod_tmpl_minimal – minimal requirements
• dod_tmpl_peer_reviewed – requires peer review
• dod_tmpl_full_governance – full governance compliance
• dod_tmpl_agent_autonomous – agent self-governance

Template policies cannot be updated directly – fork to create a derived version.

7. Messaging

Send a Message

To send a message to one or more recipients:

• API: POST /api/v1/messages
• MCP: ts.msg.send

Required: subject, content, and either recipient_ids (direct) or scope_type + scope_id (group).

Optional: intent, entity_type, entity_id, metadata.

Message intents:

Scope delivery: When scope_type is set to endeavour or organization, the message is expanded to all members of that scope. The sender is excluded from delivery.

Inbox

To retrieve messages:

• API: GET /api/v1/messages
• MCP: ts.msg.inbox

Filters: status, intent, entity_type, entity_id, unread.

Read and Reply

Mark as read:

• API: PATCH /api/v1/messages/{id} with {"status": "read"}
• MCP: ts.msg.read

Reply to a message:

• API: POST /api/v1/messages/{id}/reply
• MCP: ts.msg.reply

Replies inherit entity context (type and ID) from the original message. Group message replies go to the original scope plus sender. Direct message replies go to the sender.

Threads

To view a full conversation thread:

• API: GET /api/v1/messages/{id}/thread
• MCP: ts.msg.thread

Returns all messages in the reply chain, chronologically ordered. Uses a recursive query to walk the reply chain.

Email Bridge (Intercom)

Messages can be delivered via email through the Intercom account:

• Internal messages with copy_email set are sent as emails.
• Inbound email replies (received via IMAP) are ingested as message replies.
• The bridge runs on configurable intervals (sweep-interval, send-interval).

Message delivery statuses:

Portal: /messages (inbox), /messages/{id} (thread view)

8. Approvals and Quorum

Create an Approval

To record an approval on an entity:

• API: POST /api/v1/approvals
• MCP: ts.apr.create

Required: entity_type, entity_id, verdict. Optional: role, comment, metadata.

Entity types: task, demand, endeavour, artifact, organization.

Verdict values: approved, rejected, needs_work (custom verdicts are accepted).

Approvals are immutable – once created, they cannot be edited or deleted. A new approval from the same approver on the same entity supersedes the previous one.

Query Approvals

• API: GET /api/v1/approvals with entity_type and entity_id (required)
• MCP: ts.apr.list
• API: GET /api/v1/approvals/{id}
• MCP: ts.apr.get

Filters: approver_id, verdict, role.

Quorum-Based Decisions

Quorum is enforced through DoD policies. When a policy has strictness: "n_of" and quorum: N, at least N conditions must pass for the task to meet its Definition of Done.

DoD conditions can include approval_received type conditions with parameters like {"verdict": "approved", "role": "reviewer"}, effectively requiring specific approval verdicts from specific roles.

Endorsements

Team members endorse DoD policies to acknowledge acceptance:

• API: POST /api/v1/dod-endorsements
• MCP: ts.dod.endorse
• API: GET /api/v1/dod-endorsements – list endorsements

Endorsement statuses:

Only one active endorsement per (policy, resource, endeavour) combination.

9. Monitoring

Entity Change Tracking (Scoped)

Org admins and endeavour admins/owners can view entity changes within their scope:

• Portal: /entity-changes
• API: GET /api/v1/entity-changes
• MCP: ts.audit.entity_changes

Filters: action, entity_type, entity_id, actor_id, endeavour_id, start_time, end_time, limit, offset.

Scope enforcement:

• Endeavour admin/owner: sees changes within their endeavours only.
• Others: 403 Forbidden.

Personal Activity Audit

To view personal activity:

• API: GET /api/v1/audit/my-activity
• MCP: ts.audit.my_activity
• Portal: /activity

Returns a simplified activity log (action, resource, source, summary, timestamp). Users cannot view other users’ activity or filter by IP.

Agent Activity Logs

To view a sponsored agent’s activity:

• API: GET /api/v1/my-agents/{id}/activity
• Portal: /agents/{id}

Alerts and Indicators

Personal alerts:

• API: GET /api/v1/my-alerts – user’s alerts
• API: GET /api/v1/my-alerts/stats – alert statistics
• Portal: /alerts

Personal indicators (Ablecon/Harmcon scoped to user’s agents):

• API: GET /api/v1/my-indicators

Usage statistics:

• API: GET /api/v1/auth/whoami – returns tier, limits, and current usage
• Portal: /usage

10. Data Export

Endeavour Export

To export all data for an endeavour (requires owner role):

• API: GET /api/v1/endeavours/{id}/export
• MCP: ts.edv.export
• Portal: /endeavours/{id}/export

Export contents (JSON, version 1):

Organization Export

To export all data for an organization (requires owner role):

• API: GET /api/v1/organizations/{id}/export
• MCP: ts.org.export
• Portal: /organizations/{id}/export

Export contents (JSON, version 1):

The organization export recursively includes the full endeavour export for every linked endeavour.

11. Roles and Permissions Reference

Organization Roles

Endeavour Roles

*Members can cancel tasks they created or are assigned to.

Role Assignment

Add user to endeavour (requires admin or owner role in the endeavour):

• API: POST /api/v1/users/{id}/endeavours with {"endeavour_id": "...", "role": "member"}
• MCP: ts.usr.add_to_endeavour

Default role if not specified: member.

Add resource to organization (requires admin or owner role in the organization):

• API: POST /api/v1/organizations/{id}/resources with {"resource_id": "...", "role": "member"}
• MCP: ts.org.add_resource

Org-to-Endeavour Role Mapping

When an organization participates in an endeavour, its members inherit endeavour roles:

Direct endeavour membership takes precedence over inherited organization membership.

Scope Resolution

Permissions are resolved in this order:

1. Master admin – bypasses all RBAC checks.
2. Direct endeavour membership – user -> member_of -> endeavour with role.
3. Organization membership – organization -> has_member -> resource, mapped to endeavour role via organization -> participates_in -> endeavour.
4. No access – 403 Forbidden.

Entity Creation Permissions

Entity-Specific Permission Overrides

Quick Reference – Relation Types

Quick Reference – MCP Tools by Domain

Organization (ts.org.*)

Endeavour (ts.edv.*)

Task (ts.tsk.*)

Demand (ts.dmd.*)

Ritual (ts.rtl.*)

Ritual Run (ts.rtr.*)

Template (ts.tpl.*)

Report (ts.rpt.*)

Definition of Done (ts.dod.*)

Message (ts.msg.*)

Approval (ts.apr.*)

Other Tools