Files, connections, and integrations

Upload files when a managed service needs source material. Create a connection when it needs to use another account or tool without revealing that credential to your app workers.

File lists show metadata, not file bytes. Connection lists show safe labels and field names, not secret values.

Upload a file

const uploaded = await hive.files.upload(
  {
    name: "customer-brief.pdf",
    contentType: "application/pdf",
    bytes: new Uint8Array(await readFile("customer-brief.pdf")),
    purpose: "research-source",
  },
  { idempotencyKey: "customer-brief-pdf-v1" },
);

Files must be between 1 byte and 25 MB. The API calculates a SHA-256 checksum. You may pass a known checksum in sha256; the upload fails if it does not match.

List metadata with files.list(), download authenticated bytes with files.download(id), and delete with files.remove(id). A deleted file cannot be recreated by replaying its old idempotency key.

Store a connection

Managed connections protect credentials for an API, OAuth account, wallet, database, remote tool server, or custom integration.

const created = await hive.connections.create(
  {
    name: "Customer support source",
    kind: "api_key",
    serviceId: "hive-research",
    credentials: {
      apiKey: process.env.SUPPORT_SOURCE_KEY!,
    },
    metadata: {
      environment: "production",
      authMode: "header",
      credentialField: "apiKey",
      targetName: "x-customer-source-key",
    },
  },
  { idempotencyKey: "support-source-production-v1" },
);

The response returns only credentialFields, such as ["apiKey"]. It never returns credential values. Updating credentials rotates the protected value; deleting the connection removes it from the project.

Use connection metadata for labels and the credential mapping, never for secrets. authMode may be bearer, header, or body. credentialField chooses the protected field. Header and body mappings also require targetName. Reserved HivemindOS headers cannot be replaced.

Pass the returned connection id when the selected capability needs it:

await hive.services.invokeOperation(
  "hive-research",
  "tier.get",
  undefined,
  {
    connectionId: created.connection.id,
    idempotencyKey: "connected-tier-check-001",
  },
);

The caller needs connections:read, the connection must be active, and a service-bound connection cannot be used with a different service. HivemindOS supplies the protected credential to the managed operation and updates lastVerifiedAt after a successful response. The value is never returned to the caller. For capabilities marked approval: "always", include the same connectionId in both the approval request and the invocation.

Calendar and remote tool integrations

The integration-broker service provides managed Google Calendar and remote MCP connections without returning their OAuth or bearer credentials.

Useful capability ids include:

• connections.list
• google.oauth.start
• google.calendar.events.create
• mcp.connections.create
• mcp.invoke
• connections.revoke

google.oauth.start returns an authorization URL for the account owner. The provider callback completes the connection directly with HivemindOS. Calendar writes, new remote-tool connections, and connection revocation require an input-bound approval. Remote tool calls also pass the integration broker’s method and confirmation policy.

Security pattern

• Create and rotate credentials from a narrow project-bound key.
• Give ordinary workers connections:read only when they need connection metadata.
• Keep connections:write away from workloads that use the connected service.
• Pass a managed connectionId when a registered operation needs a protected credential; do not retrieve and forward it yourself.
• Delete a connection and revoke any provider-side grant when an integration is retired.

Next: projects and isolation, capability approvals, or the endpoint reference.