Hive#

Hive supports native action-card CSV import and selected-workspace REST v2 sync through the shared reviewable provider-import flow.

Capabilities#

Capability	Hive behavior	Status
`CSV_IMPORT`	Parse a native Table View action export into projected TeamBoost task drafts	Built
`SYNC`	Pull visible, non-archived/non-deleted actions from one Hive workspace through REST v2	Built
`USER_IMPORT`	Pull project-visible Hive users into the proposed mapping during API sync	Built (sync-coupled)
`WEBHOOK`	Verify Hive webhook callbacks	Not built

Credential and API sync#

Hive uses one encrypted, versioned JSON credential per TeamBoost organization:

{
  "version": 1,
  "apiKey": "<Hive personal API key>",
  "userId": "<Hive user id>",
  "workspaceId": "<Hive workspace id>"
}

The object must contain exactly those four keys. Values cannot be blank, and userId / workspaceId accept only letters, numbers, _, and -. Store and verify it through the generic endpoints:

PUT  /api/v1/providers/hive/credentials?organization_id=<id>
POST /api/v1/providers/hive/credentials/verify?organization_id=<id>

The whole JSON object is encrypted at rest and never returned. Verification lists Hive workspaces and succeeds only when workspaceId is visible. Current REST v2 calls send apiKey in the api_key request header. The retained userId is not sent on REST v2 requests, and there is no bearer or legacy-auth fallback.

Start a reviewable API import with:

POST /api/v1/providers/hive/imports/sync?organization_id=<id>

The sync verifies the selected workspace; lists non-archived projects and their visible users; lists workspace labels; and cursor-paginates actions with both archived and deleted filters set to false. Cursor pages use Hive's maximum documented page size. Rate limits, server errors, and network failures receive a bounded retry; invalid credentials fail with invalid_api_key, and malformed provider responses fail loudly rather than producing a partial guessed shape.

USER_IMPORT is sync-coupled: the project user directory and any stable actor ids referenced by actions become the session's proposed user mappings. There is no standalone user-import route.

Export and upload#

For one project, open the project in Hive, switch to Table View, choose More → Export → CSV, then export the file. Upload that native file through:

POST /api/v1/providers/hive/imports/csv

The endpoint requires the normal TeamBoost user token and organization scope. It creates a review session; it does not immediately create TeamBoost tasks.

The parser fingerprints the native action export through its required fields, including ID, Title, Project, Status, actor/date fields, Urgent, Milestone, Blocked, and Sections. Additional custom columns are preserved losslessly. Headers must be unique, rows must match the header width, and dates must use Hive's observed MM/DD/YYYY export format.

The first verified native shape contains either one assignee display name or Unassigned, and one label per populated cell. A row containing an unverified multi-value delimiter is reported as a row error instead of being split by a guess. Multi-project Summary View and multi-assignee exports require additional native sample validation.

Mapping behavior#

Hive value	TeamBoost draft	Behavior
`ID`	provider id + identifier	Preserved as Hive's stable opaque action id
`Title`	`title`	Direct; a title shorter than two characters is a blocking projection error
CSV with no action type	`type`	Defaults to `OTHER` with a mapping note
API `type=Feature Request` / `Bug Report`	`type`	Maps to `NEW_FEATURE` / `BUG`; other values default to `OTHER` with a note
`Status=Completed`	`status`	Maps to `COMPLETED`, including when the source also says blocked
`Status=In Progress`	`status`	Maps to `IN_PROGRESS`
`Status=Unstarted`	`status`	Maps to `NOT_STARTED`
`Blocked=Blocked` on a non-completed action	`status`	Maps to `BLOCKED`
Custom/unknown status	`status`	Left unset with a mapping note
`Urgent=true`	`priority`	Maps to `URGENT`
API `priorityLevel.name=High/Medium/Low`	`priority`	Maps to the same TeamBoost priority; custom values become `UNKNOWN` with a note
No evidence-backed priority	`priority`	Defaults to `UNKNOWN` with a mapping note
`Description`	`description`	Direct; quoted multiline content is supported
`Created by`	`creatorId` / `requestedById`	Resolved through the review mapping; an unmapped creator is advisory and remains unset
`Assignees`	`ownerId`	A present assignee must resolve to a TeamBoost member or confirmation remains blocked
`Labels` / API label ids	`labels`	CSV's observed single label is retained; API ids resolve through the workspace label directory
`Project`	`projectTitle`	Direct; Hive ids are not treated as TeamBoost project ids
`Due date`	`plannedEndDate`	Date-only values use the end of that UTC day
`Start date`, API `startDate` / `scheduledDate`	source context	Preserved without setting `plannedStartDate` until its scheduling semantics are approved
`Sections`, `Milestone`, `Parent` / `Parent ID`	`descriptionJson.exportFields`	Preserved with review notes; no task group, type change, or dependency is invented

Every CSV column, including empty and additional custom fields, and every field on each successfully normalized API action is preserved in the session's lossless source record. The API record also keeps workspace/project joins, all assignee ids, team and placeholder assignees, blocked/milestone flags, and unresolved label ids. Only the first individual assignee is proposed as owner; all other actors remain reviewable source context. UTF-8 files with or without a BOM and standard CSV quoted newlines are supported. Invalid dates, flags, row widths, or required row values appear as row errors.

Review requirements#

Before confirming the session:

Review the OTHER type and UNKNOWN priority defaults.
Resolve every present assignee to a TeamBoost member.
Review custom statuses and unmapped creators.
Inspect sections, milestones, parent actions, and start dates preserved as provider context.

projectionErrors block confirmation. mappingNotes remain advisory.

Not built yet#

Multi-assignee/multi-label parsing until native exports establish their exact cell encoding.
Webhook verification. Hive's public reference does not currently provide the signing and replay contract required by this service, and the shared webhook ingress is not built.