Create Vault Item

Creates a new vault item with fields in the specified vault.

POST /api/v1/machine/vault/:vaultId/items

Headers

Header	Type	Required	Description
`X-API-Key`	string	Yes	Your API key
`Content-Type`	string	Yes	Must be `application/json`

Path Parameters

Parameter	Type	Required	Description
`vaultId`	string	Yes	The unique identifier of the vault to add the item to

Request Body

Field	Type	Required	Description
`name`	string	Yes	The name of the vault item (max 255 characters)
`type`	string	Yes	The item type (see Item Types below)
`websites`	string[]	No	Associated website URLs
`fields`	array	Yes	Fields to create on the vault item

Field Object

Field	Type	Required	Description
`name`	string	Yes	The field label (e.g., "Username", "Password")
`type`	string	Yes	The field type (see Field Types below)
`value`	string	No	The field value
`isSecret`	boolean	No	Override: force this field to be stored as a secret

Item Types

Type	Description
`LOGIN`	Login credentials (username/password)
`API_KEY`	API key or token
`DATABASE`	Database connection details
`SSH_KEY`	SSH key pair
`SERVER`	Server access credentials
`SECURE_NOTE`	Encrypted text note
`CREDIT_CARD`	Payment card information
`CUSTOM`	Custom item with arbitrary fields

Field Types

Type	Default Secret	Description
`TEXT`	No	Plain text value
`PASSWORD`	Yes	Password (stored encrypted)
`SECRET`	Yes	Generic secret value
`URL`	No	URL value
`NUMBER`	No	Numeric value
`TOTP`	Yes	Time-based one-time password seed
`FILE`	No	File attachment reference

Response

Success (201 Created)

{
  "id": "507f1f77bcf86cd799439014"
}

Response Fields

Field	Type	Description
`id`	string	The unique identifier of the newly created vault item

Error Responses

404 Not Found - Vault not found or not accessible

{
  "error": {
    "code": "vault_not_found",
    "message": "The vault with ID \"abc123\" was not found or you do not have access to it."
  }
}

400 Bad Request - Invalid request body

{
  "error": {
    "code": "vault_item_creation_failed",
    "message": "Failed to create the vault item. Please verify your input and try again."
  }
}

Example Request

curl -X POST "https://r4.dev/api/v1/machine/vault/507f1f77bcf86cd799439011/items" \
  -H "X-API-Key: rk_abc123def456.ghijklmnopqrstuvwxyz" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Database",
    "type": "LOGIN",
    "websites": ["https://db.example.com"],
    "fields": [
      {
        "name": "Host",
        "type": "TEXT",
        "value": "db.example.com"
      },
      {
        "name": "Port",
        "type": "NUMBER",
        "value": "5432"
      },
      {
        "name": "Username",
        "type": "TEXT",
        "value": "admin"
      },
      {
        "name": "Password",
        "type": "PASSWORD",
        "value": "super_secret_password"
      }
    ]
  }'

Use Cases

Secret provisioning: Programmatically store credentials generated during infrastructure deployment
Rotation automation: Create new vault items after rotating secrets
Migration: Bulk-import secrets from another secrets manager
CI/CD: Store build artifacts and deployment credentials automatically