Poiva
Integrate Whitepaper Poiva Cloud
Versioned object model for interoperable fulfilment Reference specification

A FHIR-style reference surface for Poiva models, links, and APIs.

This page presents the core protocol as a maintainable catalog: model definitions, typed attributes, inferred relationships, example payloads, and transport surfaces all generated from a single set of definitions.

Update the model catalog once and the attribute tables, typed links, example panels, and relationship summaries stay aligned automatically.

Protocol scope Implementation path

Reference specification

12 core models
43 typed links
3 API surfaces
draftplannedprovisionedexecutingsubmittedverifyingsettled
Example views

Switch the same model catalog into real-world protocol instances.

Choose a domain scenario and every model card can show realistic values without changing the underlying definition.

Model catalog

Typed definitions, inferred references, and live examples.

The attribute tables stay protocol-focused while the example panels translate those definitions into software, healthcare, logistics, and legal instances.

Mission

The primary protocol object that captures the intended outcome, owning sponsor, lifecycle state, policy hooks, and required outputs.

Core model

Real instance

Production feature release

A product sponsor requests a feature rollout with CI and release approval gates.

id mission-soft-2048
status planned
intentSummary Ship approval workflow to production this sprint
sponsor participant-product-ops
Attribute Type Card. Presence Description
id id 1..1 Required Stable protocol identifier for the mission.
status code 1..1 Required Lifecycle state such as draft, planned, active, verifying, or settled.
intentSummary string 1..1 Required Compact statement of the outcome the network must fulfil.
sponsor Reference(Participant) 1..1 Required The accountable requester, team, or organization funding the mission.
deliverables Reference(Deliverable) 0..* Optional Expected deliverables that satisfy the mission when accepted.
verificationPolicy Reference(Verification) 0..1 Optional The verification definition used to evaluate completion.
extensions Reference(ExtensionField) 0..* Optional Additive extension fields attached to this entity.

Typed links inferred from attributes

sponsor Participant deliverables Deliverable verificationPolicy Verification extensions ExtensionField
GET
/missions/{id}

Read the canonical mission state.

POST
/missions

Create a new mission request.

GET
/missions?status=active

Query missions by lifecycle state.

PATCH
/missions/{id}

Update mission scope, lifecycle state, or policy references.

DELETE
/missions/{id}

Withdraw a draft mission before fulfilment begins.

Activity

The executable work unit inside a mission, including owner, sequencing, inputs, and produced outputs.

Core model

Real instance

Backend implementation activity

One activity in the release mission covers API changes, tests, and rollout notes.

type implementation
state executing
assignee participant-backend-engineer
output deliverable-pr-981
Attribute Type Card. Presence Description
id id 1..1 Required Stable identifier for the activity node.
mission Reference(Mission) 1..1 Required Owning mission for the activity.
type code 1..1 Required Categorizes the work such as review, transport, inspection, coding, or approval.
state code 1..1 Required Draft, ready, executing, blocked, submitted, or accepted.
assignee Reference(Participant) 0..1 Optional Assigned human, team, AI agent, or system.
output Reference(Deliverable) 0..1 Optional Primary deliverable emitted by this activity.
extensions Reference(ExtensionField) 0..* Optional Additive extension fields attached to this entity.

Typed links inferred from attributes

mission Mission assignee Participant output Deliverable extensions ExtensionField
GET
/activities/{id}

Read one activity and its execution state.

POST
/missions/{id}/activities

Append a planned activity to a mission.

POST
/activities/{id}/submit

Submit activity output for verification.

PATCH
/activities/{id}

Revise assignee, sequencing, or state transitions.

DELETE
/activities/{id}

Remove an obsolete draft activity from a mission plan.

Organization

The tenant-root object for Poiva Cloud and the protocol's organizational boundary for members, missions, and governance.

Core model

Real instance

Poiva Labs

A software team signs up an organization and adds the first owner.

name Poiva Labs
slug poiva-labs
primaryEmail ops@poiva.dev
status ACTIVE
Attribute Type Card. Presence Description
id id 1..1 Required Stable organization identifier.
name string 1..1 Required Human-readable organization name.
slug string 1..1 Required URL-safe unique organization identifier.
primaryEmail string 1..1 Required Primary contact email or signup anchor for the organization.
status code 1..1 Required ACTIVE or SUSPENDED.
owner Reference(Participant) 0..1 Optional Owner participant responsible for the tenant.
members Reference(Participant) 0..* Optional Participants belonging to the organization.
missions Reference(Mission) 0..* Optional Missions that belong to the organization.
extensions Reference(ExtensionField) 0..* Optional Additive extension fields attached to this entity.

Typed links inferred from attributes

owner Participant members Participant missions Mission extensions ExtensionField
GET
/organizations/{id}

Read a tenant organization.

POST
/organizations

Create a new organization.

PATCH
/organizations/{id}

Update the organization profile or status.

DELETE
/organizations/{id}

Deactivate a tenant organization.

Pool

A bounded collection of participants grouped by purpose: intent creators, estimators, or fulfillment resources, with optional additive metadata.

Core model

Real instance

Frontend release pool

A pool for creators, estimators, and release resources collaborating on a release mission.

name Frontend release pool
type mixed
organization organization-poiva-labs
participants participant-product-owner, participant-estimator-1, participant-frontend-engineer
Attribute Type Card. Presence Description
id id 1..1 Required Stable pool identifier.
name string 1..1 Required Human-readable pool name.
type code 1..1 Required intent-creators, estimators, fulfillment-resources, or mixed.
organization Reference(Organization) 0..1 Optional Tenant that owns the pool.
participants Reference(Participant) 0..* Optional Participants included in the pool.
extensions Reference(ExtensionField) 0..* Optional Additive extension fields attached to this entity.

Typed links inferred from attributes

organization Organization participants Participant extensions ExtensionField
GET
/pools/{id}

Read one pool and its participants.

POST
/pools

Create a pool for a participant cohort.

PATCH
/pools/{id}

Update pool metadata or participant membership.

DELETE
/pools/{id}

Archive a pool that is no longer active.

ExtensionField

A generic name/value pair attached to any protocol entity for additive metadata and domain-specific augmentation.

Core model

Real instance

Release metadata

Add additive metadata to a mission or deliverable without changing the base protocol shape.

entityType mission
entityId mission-soft-2048
name release-train
value Q3 platform hardening
Attribute Type Card. Presence Description
id id 1..1 Required Stable extension identifier.
entityType code 1..1 Required Protocol entity type that owns the extension.
entityId id 1..1 Required Identifier of the entity receiving the extension.
name string 1..1 Required Extension key, up to 500 characters.
value text 1..1 Required Extension value stored as long text.

Typed links inferred from attributes

No typed references defined on this model.

GET
/extension-fields/{id}

Read an extension field.

POST
/extension-fields

Attach an extension field to any entity.

PATCH
/extension-fields/{id}

Update the extension name or value.

DELETE
/extension-fields/{id}

Remove an extension field from an entity.

Participant

A fulfilment actor: human specialist, organization, AI agent, robot, or automation service contributing to protocol work.

Core model

Real instance

Backend engineer

A human contributor with Java, testing, and API delivery capabilities.

kind human
displayName Mara Ionescu
organization organization-poiva-labs
capabilities capability-java-platform, capability-api-testing
availability Sprint capacity: 60%
Attribute Type Card. Presence Description
id id 1..1 Required Stable participant identifier.
kind code 1..1 Required human | organization | ai-agent | robot | system.
displayName string 1..1 Required Human-readable participant label.
organization Reference(Organization) 0..1 Optional Organization the participant belongs to or is provisioned through.
capabilities Reference(Capability) 0..* Optional Typed capabilities used during provisioning and matching.
homeMission Reference(Mission) 0..1 Optional Optional current mission context when rendered in a workflow.
availability string 0..1 Optional Availability window or dispatch state.
extensions Reference(ExtensionField) 0..* Optional Additive extension fields attached to this entity.

Typed links inferred from attributes

organization Organization capabilities Capability homeMission Mission extensions ExtensionField
GET
/participants/{id}

Read one participant profile.

GET
/participants?capability=clinical-review

Find participants by capability.

POST
/participants

Register a new participant in the protocol.

PATCH
/participants/{id}

Update participant availability, metadata, or capability posture.

DELETE
/participants/{id}

Deactivate a participant from future provisioning.

Capability

Reusable declarations of what participants can do, independent of titles, vendors, or local organizational charts.

Core model

Real instance

Java platform delivery

A capability describing enterprise Java implementation and rollout readiness.

code java-platform-delivery
display Java platform delivery
evidenceHints PRs, CI runs, security scans
participant participant-backend-engineer
Attribute Type Card. Presence Description
id id 1..1 Required Stable capability identifier.
code code 1..1 Required Machine-readable capability code.
display string 1..1 Required Human-readable capability label.
evidenceHints string 0..* Optional Typical evidence used to prove the capability or its output quality.
participant Reference(Participant) 0..* Optional Participants advertising this capability.
knowledgeRequirements Reference(Knowledge) 0..* Optional Referenced knowledge or policy context needed to exercise it.
extensions Reference(ExtensionField) 0..* Optional Additive extension fields attached to this entity.

Typed links inferred from attributes

participant Participant knowledgeRequirements Knowledge extensions ExtensionField
GET
/capabilities/{id}

Read a capability definition.

GET
/capabilities?code=route-planning

Search by capability code.

POST
/capabilities

Register a new capability definition.

PATCH
/capabilities/{id}

Refine metadata or evidence hints for a capability.

DELETE
/capabilities/{id}

Retire a capability code from active use.

Knowledge

Immutable context objects that missions and activities rely on: documents, repositories, policies, diagrams, URLs, datasets, or media.

Core model

Real instance

Release architecture note

The mission references a repository path and rollout checklist.

type repository-doc
locator https://git.example.com/poiva/releases/approval-workflow.md
mission mission-soft-2048
maintainer participant-platform-lead
Attribute Type Card. Presence Description
id id 1..1 Required Stable knowledge identifier.
type code 1..1 Required Policy, repository, contract, chart, scan, route-map, media, or dataset.
locator uri 1..1 Required Resolvable external or internal location for the knowledge item.
mission Reference(Mission) 0..1 Optional Mission context the knowledge belongs to.
maintainer Reference(Participant) 0..1 Optional Actor maintaining or approving the knowledge artifact.
supersedes Reference(Knowledge) 0..1 Optional Previous knowledge artifact replaced by this one.
extensions Reference(ExtensionField) 0..* Optional Additive extension fields attached to this entity.

Typed links inferred from attributes

mission Mission maintainer Participant supersedes Knowledge extensions ExtensionField
GET
/knowledge/{id}

Read one knowledge object.

POST
/knowledge

Register a knowledge artifact in the protocol.

GET
/knowledge?mission=mission-soft-2048

Query mission-bound knowledge.

PATCH
/knowledge/{id}

Update metadata or supersession links for a knowledge item.

DELETE
/knowledge/{id}

Detach a superseded draft knowledge item.

Deliverable

The candidate output submitted for acceptance: document, deployment, completed trip, inspection report, or other domain-specific result.

Core model

Real instance

Merged release package

The deliverable bundles the pull request, deployment manifest, and release notes.

artifactType pull-request-package
producedBy activity-backend-implementation
submittedBy participant-backend-engineer
evidence evidence-ci-229, evidence-scan-08
Attribute Type Card. Presence Description
id id 1..1 Required Stable deliverable identifier.
mission Reference(Mission) 1..1 Required Mission satisfied by the deliverable.
producedBy Reference(Activity) 0..1 Optional Activity primarily responsible for the output.
artifactType code 1..1 Required PR, deployment, PDF, report, route completion, approval pack, and similar.
submittedBy Reference(Participant) 1..1 Required The actor who submits the deliverable.
evidence Reference(Evidence) 0..* Optional Evidence items supporting the deliverable.
extensions Reference(ExtensionField) 0..* Optional Additive extension fields attached to this entity.

Typed links inferred from attributes

mission Mission producedBy Activity submittedBy Participant evidence Evidence extensions ExtensionField
GET
/deliverables/{id}

Read a deliverable and its evidence graph.

POST
/deliverables

Submit a deliverable for a mission.

POST
/deliverables/{id}/evidence

Attach evidence to an existing deliverable.

PATCH
/deliverables/{id}

Revise metadata or replace a pending deliverable submission.

DELETE
/deliverables/{id}

Retract a deliverable that has not yet been accepted.

Evidence

Portable proof used to validate deliverables: events, files, signatures, checksums, photos, measurements, ratings, or approvals.

Core model

Real instance

CI and security proof

Machine-generated evidence proves the release passed required checks.

type test-run
subject deliverable-pr-981
collectedBy participant-ci-system
payloadLocator https://ci.example.com/runs/229
Attribute Type Card. Presence Description
id id 1..1 Required Stable evidence identifier.
subject Reference(Deliverable) 1..1 Required Deliverable or activity substantiated by the evidence.
type code 1..1 Required Signature, scan, test-run, photo, audit-note, reading, GPS trail, or approval.
collectedBy Reference(Participant) 0..1 Optional Actor or system that collected the evidence.
sourceKnowledge Reference(Knowledge) 0..1 Optional Knowledge object describing the origin context.
payloadLocator uri 1..1 Required Where the proof artifact can be retrieved or replayed.
extensions Reference(ExtensionField) 0..* Optional Additive extension fields attached to this entity.

Typed links inferred from attributes

subject Deliverable collectedBy Participant sourceKnowledge Knowledge extensions ExtensionField
GET
/evidence/{id}

Read one evidence item.

POST
/evidence

Register evidence independently.

GET
/evidence?subject=deliverable-proof-of-delivery

Query evidence by subject.

PATCH
/evidence/{id}

Correct metadata or add correlation tags to an evidence item.

DELETE
/evidence/{id}

Remove invalid evidence before verification closes.

Verification

The evaluation resource that interprets evidence against policy and returns an acceptance decision the network can trust.

Core model

Real instance

Release gate verification

The verifier checks merged status, CI health, and security policy before release.

policyCode release-ready-v3
target deliverable-pr-981
reviewer participant-release-manager
decision accepted
Attribute Type Card. Presence Description
id id 1..1 Required Stable verification identifier.
target Reference(Deliverable) 1..1 Required Deliverable under evaluation.
policyCode code 1..1 Required Verification policy or rule-set identifier.
evidence Reference(Evidence) 1..* Required Evidence bundle evaluated by the verifier.
reviewer Reference(Participant) 0..1 Optional Human or system reviewer producing the decision.
decision code 1..1 Required accepted | rejected | revise.
extensions Reference(ExtensionField) 0..* Optional Additive extension fields attached to this entity.

Typed links inferred from attributes

target Deliverable evidence Evidence reviewer Participant extensions ExtensionField
GET
/verifications/{id}

Read the verification decision and rationale.

POST
/verifications

Create a verification request.

POST
/verifications/{id}/evaluate

Run the verification policy against evidence.

PATCH
/verifications/{id}

Update reviewer assignment or decision notes before finalization.

DELETE
/verifications/{id}

Cancel a pending verification request.

Event

Immutable history emitted whenever protocol state changes, enabling replay, auditability, analytics, and cross-system synchronization.

Core model

Real instance

Deployment event

An immutable record marks the release package as submitted for verification.

type deliverable.submitted
occurredAt 2026-08-04T09:14:00Z
mission mission-soft-2048
actor participant-backend-engineer
Attribute Type Card. Presence Description
id id 1..1 Required Stable event identifier.
type code 1..1 Required Event category such as mission.created or deliverable.submitted.
occurredAt instant 1..1 Required Wall-clock timestamp for the emitted event.
mission Reference(Mission) 0..1 Optional Mission correlated with the event.
actor Reference(Participant) 0..1 Optional Actor causing or observing the transition.
subject Reference(Deliverable) 0..1 Optional Optional subject resource impacted by the event.
extensions Reference(ExtensionField) 0..* Optional Additive extension fields attached to this entity.

Typed links inferred from attributes

mission Mission actor Participant subject Deliverable extensions ExtensionField
GET
/events/{id}

Read one immutable event.

GET
/events?mission=mission-soft-2048

Replay mission history.

GET
/events/stream

Subscribe to protocol events.

PATCH
/events/{id}/annotations

Append non-semantic operator annotations to an event.

DELETE
/events/{id}/annotations/{annotationId}

Remove an operator annotation while keeping the event immutable.

Relationship matrix

Reference links are generated from the model definitions.

When an attribute changes from a scalar to a typed reference, this matrix updates from the same source of truth.

Activity / mission

References Mission

1..1
Organization / missions

References Mission

0..*
Participant / capabilities

References Capability

0..*
Participant / homeMission

References Mission

0..1
Capability / knowledgeRequirements

References Knowledge

0..*
Knowledge / mission

References Mission

0..1
Knowledge / supersedes

References Knowledge

0..1
Deliverable / mission

References Mission

1..1
Deliverable / producedBy

References Activity

0..1
Deliverable / submittedBy

References Participant

1..1
Deliverable / evidence

References Evidence

0..*
Evidence / sourceKnowledge

References Knowledge

0..1
Verification / evidence

References Evidence

1..*
Event / mission

References Mission

0..1
API surfaces

REST and event interfaces over one protocol core.

Resource APIs

Canonical endpoints for core protocol resources.

GET
/organizations/{id}

Fetch an organization and its members.

POST
/organizations

Create an organization tenant.

GET
/missions/{id}

Fetch a mission with links to activities and deliverables.

GET
/deliverables/{id}

Fetch one deliverable and supporting evidence.

GET
/participants?capability={code}

Find fulfilment capacity by capability.

PATCH
/missions/{id}

Apply partial lifecycle or policy updates without replacing the resource.

DELETE
/missions/{id}

Cancel a draft mission before execution starts.

Workflow APIs

Actions that move work through the lifecycle.

POST
/api/cloud/signup

Create a tenant organization and first owner account.

POST
/api/cloud/login

Exchange email and password for an access token.

POST
/missions

Create a mission from an external intent.

POST
/activities/{id}/submit

Submit a completed activity output.

POST
/verifications/{id}/evaluate

Run verification for a deliverable.

PATCH
/deliverables/{id}

Revise a deliverable before acceptance.

DELETE
/verifications/{id}

Abort a pending verification workflow.

Event and sync surfaces

For analytics, orchestration, and cross-system federation.

GET
/events?mission={id}

Replay immutable mission history.

GET
/events/stream

Subscribe to event emission.

POST
/evidence

Register proof emitted by external systems.

PATCH
/events/{id}/annotations

Attach operator annotations without mutating event semantics.

DELETE
/events/{id}/annotations/{annotationId}

Remove an annotation while preserving the underlying event.

Specification guarantees

Stable semantics first, implementation freedom second.

Typed references preserve meaning across implementations.
Examples switch by use case without duplicating the model definition.
Relationships are inferred from attribute references so the graph stays in sync.
REST, events, and policy evaluation are interface choices over one protocol core.
Explore SDKs See industry overlays