API Reference

This document provides detailed information about all API endpoints.

Domain Manager

The Domain Manager API provides programmatic access to DNS management for domains in your organization.

Get DNS Records

Retrieves all DNS records configured for a domain managed by your organization.

GET /api/v1/machine/domain-manager/dns-records

Query Parameters

Parameter	Type	Required	Description
`domain`	string	Yes	The domain name to retrieve DNS records for (e.g., "example.com")

Headers

Header	Type	Required	Description
`X-API-Key`	string	Yes	Your API key

Response

Success (200 OK)

{
  "domain": "example.com",
  "records": [
    {
      "type": "A",
      "name": "@",
      "value": "192.168.1.1",
      "ttl": 300
    },
    {
      "type": "CNAME",
      "name": "www",
      "value": "example.com.",
      "ttl": 300
    },
    {
      "type": "MX",
      "name": "@",
      "value": "mail.example.com.",
      "ttl": 300,
      "mxPref": 10
    },
    {
      "type": "TXT",
      "name": "@",
      "value": "v=spf1 include:_spf.google.com ~all",
      "ttl": 300
    }
  ]
}

Response Fields

Field	Type	Description
`domain`	string	The domain name
`records`	array	Array of DNS records
`records[].type`	string	Record type (A, AAAA, CNAME, MX, TXT, NS, SRV, CAA)
`records[].name`	string	Host name ("@" for root, or subdomain like "www")
`records[].value`	string	Record value (IP, hostname, or text)
`records[].ttl`	number	Time to live in seconds
`records[].mxPref`	number	MX priority (only for MX records)

Error Responses

401 Unauthorized - Invalid or missing API key

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key. Please provide your API key in the X-API-Key header."
  }
}

403 Forbidden - Domain not managed through R4

{
  "error": {
    "code": "domain_not_managed",
    "message": "The domain \"example.com\" is not managed through R4. DNS records can only be retrieved for domains purchased through the R4 platform."
  }
}

404 Not Found - Domain not found in your organization

{
  "error": {
    "code": "domain_not_found",
    "message": "The domain \"example.com\" was not found in your organization or you do not have access to it."
  }
}

Example Request

curl -X GET "https://r4.dev/api/v1/machine/domain-manager/dns-records?domain=example.com" \
  -H "X-API-Key: rk_abc123def456.ghijklmnopqrstuvwxyz1234567890abcdef"

Use Cases

Infrastructure auditing: Verify DNS configuration across your domains
Monitoring: Build dashboards showing current DNS settings
Pre-deployment checks: Validate DNS before deploying applications
Documentation: Automatically document your DNS configuration

Notes

Only domains purchased through R4 (internalPurchase: true) can have their DNS records retrieved
External domains (registered elsewhere) are not accessible through this endpoint
The domain must be associated with a tenant in your organization

Add DNS Record

Adds a new DNS record to a domain managed by your organization.

POST /api/v1/machine/domain-manager/dns-records

Headers

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

Request Body

Field	Type	Required	Description
`domain`	string	Yes	The domain name to add the record to (e.g., "example.com")
`record`	object	Yes	The DNS record to add
`record.type`	string	Yes	Record type (A, AAAA, CNAME, MX, TXT, NS, SRV, CAA)
`record.name`	string	Yes	Host name ("@" for root, or subdomain like "www")
`record.value`	string	Yes	Record value (IP address, hostname, or text)
`record.ttl`	number	No	Time to live in seconds (default: 300)
`record.mxPref`	number	No	MX priority (only for MX records, lower = higher priority)

Example Request Body

{
  "domain": "example.com",
  "record": {
    "type": "A",
    "name": "www",
    "value": "192.168.1.1",
    "ttl": 300
  }
}

Response

Success (200 OK)

Returns all DNS records for the domain, including the newly added record.

{
  "domain": "example.com",
  "records": [
    {
      "type": "A",
      "name": "@",
      "value": "192.168.1.1",
      "ttl": 300
    },
    {
      "type": "A",
      "name": "www",
      "value": "192.168.1.1",
      "ttl": 300
    },
    {
      "type": "CNAME",
      "name": "mail",
      "value": "example.com.",
      "ttl": 300
    }
  ]
}

Error Responses

401 Unauthorized - Invalid or missing API key

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key. Please provide your API key in the X-API-Key header."
  }
}

403 Forbidden - Domain not managed through R4

{
  "error": {
    "code": "domain_not_managed",
    "message": "The domain \"example.com\" is not managed through R4. DNS records can only be modified for domains purchased through the R4 platform."
  }
}

404 Not Found - Domain not found in your organization

{
  "error": {
    "code": "domain_not_found",
    "message": "The domain \"example.com\" was not found in your organization or you do not have access to it."
  }
}

Example Request

curl -X POST "https://r4.dev/api/v1/machine/domain-manager/dns-records" \
  -H "X-API-Key: rk_abc123def456.ghijklmnopqrstuvwxyz1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "domain": "example.com",
    "record": {
      "type": "A",
      "name": "www",
      "value": "192.168.1.1",
      "ttl": 300
    }
  }'

Use Cases

Infrastructure automation: Automatically configure DNS when provisioning servers
CI/CD pipelines: Set up DNS records as part of deployment workflows
Subdomain management: Programmatically create subdomains for new services
Email configuration: Add MX, SPF, and DKIM records for email setup
Domain verification: Add TXT records for third-party service verification

Notes

Only domains purchased through R4 (internalPurchase: true) can have their DNS records modified
External domains (registered elsewhere) cannot be modified through this endpoint
The domain must be associated with a tenant in your organization
DNS changes may take time to propagate (typically 5 minutes to 48 hours depending on TTL)
The response includes all DNS records for the domain, not just the newly added one

Project Manager

The Project Manager API provides programmatic access to project creation, listing, and detailed resource information. Projects are organizational units that contain vaults, licenses, and license groups.

List Projects

Retrieves a list of all non-archived projects accessible to the authenticated API key.

GET /api/v1/machine/project

Headers

Header	Type	Required	Description
`X-API-Key`	string	Yes	Your API key

Response

Success (200 OK)

{
  "projects": [
    {
      "id": "507f1f77bcf86cd799439014",
      "name": "Production Infrastructure",
      "externalId": "PROJ-001",
      "description": "Contains all production environment resources",
      "vaultsCount": 5,
      "licensesCount": 12,
      "licenseGroupsCount": 3,
      "archivedAt": null
    },
    {
      "id": "507f1f77bcf86cd799439015",
      "name": "Development Environment",
      "externalId": "PROJ-002",
      "description": "Development and testing resources",
      "vaultsCount": 2,
      "licensesCount": 4,
      "licenseGroupsCount": 1,
      "archivedAt": null
    }
  ]
}

Response Fields

Field	Type	Description
`projects`	array	Array of project summary objects

Project Summary Fields

Field	Type	Description
`id`	string	The unique identifier of the project
`name`	string	The name of the project
`externalId`	string \| null	Optional external identifier for integration with external systems
`description`	string \| null	A description of the project
`vaultsCount`	number	The number of vaults associated with this project
`licensesCount`	number	The number of licenses (both internal and manual) associated
`licenseGroupsCount`	number	The number of license groups associated
`archivedAt`	string \| null	ISO 8601 timestamp when archived (null if active)

Error Responses

401 Unauthorized - Invalid or missing API key

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key. Please provide your API key in the X-API-Key header."
  }
}

Example Request

curl -X GET "https://r4.dev/api/v1/machine/project" \
  -H "X-API-Key: rk_abc123def456.ghijklmnopqrstuvwxyz1234567890abcdef"

Create Project

Creates a new project in the organization.

POST /api/v1/machine/project

Headers

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

Request Body

Field	Type	Required	Description
`name`	string	Yes	The name of the project (max 255 characters)
`externalId`	string	No	Optional external identifier for integration (max 255 characters)
`description`	string	No	A description of the project (max 1000 characters)

Response

Success (201 Created)

{
  "id": "507f1f77bcf86cd799439014"
}

Response Fields

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

Error Responses

400 Bad Request - Invalid request body

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

401 Unauthorized - Invalid or missing API key

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key. Please provide your API key in the X-API-Key header."
  }
}

Example Request

curl -X POST "https://r4.dev/api/v1/machine/project" \
  -H "X-API-Key: rk_abc123def456.ghijklmnopqrstuvwxyz1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Infrastructure",
    "externalId": "PROJ-001",
    "description": "Contains all production environment resources"
  }'

Get Project Details

Retrieves detailed information about a project including all associated vaults, licenses, and license groups.

GET /api/v1/machine/project/:id

Path Parameters

Parameter	Type	Required	Description
`id`	string	Yes	The unique identifier of the project

Headers

Header	Type	Required	Description
`X-API-Key`	string	Yes	Your API key

Response

Success (200 OK)

{
  "id": "507f1f77bcf86cd799439014",
  "name": "Production Infrastructure",
  "externalId": "PROJ-001",
  "description": "Contains all production environment resources",
  "domainTenantId": "507f1f77bcf86cd799439016",
  "vaultsCount": 5,
  "licensesCount": 12,
  "licenseGroupsCount": 3,
  "createdAt": "2026-01-15T10:30:00.000Z",
  "createdBy": "507f1f77bcf86cd799439017",
  "archivedAt": null,
  "vaults": [
    {
      "id": "507f1f77bcf86cd799439011",
      "name": "Production Secrets",
      "isEncrypted": true
    }
  ],
  "licenses": [
    {
      "id": "507f1f77bcf86cd799439012",
      "name": "Enterprise License",
      "type": "internal"
    },
    {
      "id": "507f1f77bcf86cd799439018",
      "name": "Manual License Entry",
      "type": "manual"
    }
  ],
  "licenseGroups": [
    {
      "id": "507f1f77bcf86cd799439013",
      "name": "Development Team Licenses"
    }
  ]
}

Response Fields

Field	Type	Description
`id`	string	The unique identifier of the project
`name`	string	The name of the project
`externalId`	string \| null	Optional external identifier for integration with external systems
`description`	string \| null	A description of the project
`domainTenantId`	string \| null	The domain tenant ID this project is associated with
`vaultsCount`	number	The number of vaults associated with this project
`licensesCount`	number	The number of licenses (both internal and manual) associated
`licenseGroupsCount`	number	The number of license groups associated
`createdAt`	string	ISO 8601 timestamp when the project was created
`createdBy`	string	ID of the user who created the project
`archivedAt`	string \| null	ISO 8601 timestamp when archived (null if active)
`vaults`	array	Array of vault objects associated with the project
`licenses`	array	Array of license objects (both internal and manual)
`licenseGroups`	array	Array of license group objects

Vault Object Fields

Field	Type	Description
`id`	string	The unique identifier of the vault
`name`	string	The name of the vault
`isEncrypted`	boolean \| null	Whether the vault uses client-side encryption

License Object Fields

Field	Type	Description
`id`	string	The unique identifier of the license
`name`	string \| null	The name of the license
`type`	string	License type: "internal" or "manual"

License Group Object Fields

Field	Type	Description
`id`	string	The unique identifier of the license group
`name`	string	The name of the license group

Error Responses

401 Unauthorized - Invalid or missing API key

{
  "error": {
    "code": "unauthorized",
    "message": "Invalid or missing API key. Please provide your API key in the X-API-Key header."
  }
}

404 Not Found - Project not found in your organization

{
  "error": {
    "code": "project_not_found",
    "message": "The project with ID \"507f1f77bcf86cd799439014\" was not found in your organization or you do not have access to it."
  }
}

Example Request

curl -X GET "https://r4.dev/api/v1/machine/project/507f1f77bcf86cd799439014" \
  -H "X-API-Key: rk_abc123def456.ghijklmnopqrstuvwxyz1234567890abcdef"

Notes

The project must belong to your organization
The API key must have access to the tenant associated with the project
Only non-archived vaults, licenses, and license groups are included in the response

Vault Manager

The Vault Manager API provides full programmatic access to vault management — creating vaults, managing vault items, and retrieving secrets.

Create Vault

Creates a new encrypted vault with scope-based default permissions.

POST /api/v1/machine/vault

Headers

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

Request Body

Field	Type	Required	Description
`name`	string	Yes	The name of the vault (max 255 chars)
`encryptionKeyId`	string	Yes	Encryption key ID. Encryption is required for all machine-created vaults.
`projectId`	string	No	Project ID to grant WRITE access to the vault
`dataClassification`	string	No	Data classification level: `PUBLIC`, `INTERNAL`, `CONFIDENTIAL`, or `CUI`

Response

Success (201 Created)

{
  "id": "507f1f77bcf86cd799439016"
}

Permissions

AGENT-scoped API keys: The agent is granted ADMIN access
USER/TENANT/ORG-scoped API keys: The session user is granted ADMIN access
If projectId is provided, the project is additionally granted WRITE access

Example Request

curl -X POST "https://r4.dev/api/v1/machine/vault" \
  -H "X-API-Key: rk_abc123def456.ghijklmnopqrstuvwxyz1234567890abcdef" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production Secrets",
    "encryptionKeyId": "507f1f77bcf86cd799439015",
    "projectId": "507f1f77bcf86cd799439014",
    "dataClassification": "CONFIDENTIAL"
  }'

List Vaults

Returns all accessible vaults, optionally filtered by project.

GET /api/v1/machine/vault

Query Parameters

Parameter	Type	Required	Description
`projectId`	string	No	Filter vaults by project ID

Response

Success (200 OK)

{
  "vaults": [
    {
      "id": "507f1f77bcf86cd799439011",
      "name": "Production Secrets",
      "isEncrypted": true,
      "encryptionKeyId": "507f1f77bcf86cd799439015",
      "dataClassification": "CONFIDENTIAL",
      "itemCount": 12,
      "createdAt": "2026-01-15T10:30:00.000Z"
    }
  ]
}

Example Request

curl -X GET "https://r4.dev/api/v1/machine/vault?projectId=507f1f77bcf86cd799439014" \
  -H "X-API-Key: rk_abc123def456.ghijklmnopqrstuvwxyz1234567890abcdef"

Get Vault Detail

Returns detailed information about a specific vault.

GET /api/v1/machine/vault/:vaultId

Path Parameters

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

Response

Success (200 OK)

{
  "id": "507f1f77bcf86cd799439011",
  "name": "Production Secrets",
  "isEncrypted": true,
  "encryptionKeyId": "507f1f77bcf86cd799439015",
  "dataClassification": "CONFIDENTIAL",
  "createdAt": "2026-01-15T10:30:00.000Z",
  "createdBy": "507f1f77bcf86cd799439017",
  "itemCount": 12
}

Archive Vault

Archives (soft-deletes) a vault. The vault and its items are retained for audit purposes.

DELETE /api/v1/machine/vault/:vaultId

Path Parameters

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

Response

Success (204 No Content)

No response body.

Create Vault Item

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

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

Path Parameters

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

Request Body

Field	Type	Required	Description
`name`	string	Yes	The name of the vault item (max 255 chars)
`type`	string	Yes	Vault item type (e.g., `LOGIN`, `API_KEY`)
`websites`	array	No	Associated website URLs (max 100)
`fields`	array	Yes	Array of field objects to create on the item

Field Object

Field	Type	Required	Description
`name`	string	Yes	Field label (e.g., "Username", "Password")
`type`	string	Yes	Field type (TEXT, PASSWORD, SECRET, URL, EMAIL, etc.)
`value`	string	No	The field value
`isSecret`	boolean	No	Override default secret detection for this field

Response

Success (201 Created)

{
  "id": "507f1f77bcf86cd799439018"
}

Example Request

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

List Vault Items

Returns all non-archived items in a vault with basic metadata.

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

Path Parameters

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

Response

Success (200 OK)

{
  "items": [
    {
      "id": "507f1f77bcf86cd799439018",
      "name": "Production Database",
      "type": "LOGIN",
      "websites": ["https://db.example.com"],
      "createdAt": "2026-01-15T10:30:00.000Z",
      "fieldCount": 2
    }
  ],
  "vaultId": "507f1f77bcf86cd799439011",
  "count": 1
}

Get Vault Item Detail

Returns full vault item detail including all fields and their values.

GET /api/v1/machine/vault/:vaultId/items/:itemId

Path Parameters

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

Response

Success (200 OK)

{
  "id": "507f1f77bcf86cd799439018",
  "name": "Production Database",
  "type": "LOGIN",
  "websites": ["https://db.example.com"],
  "vaultId": "507f1f77bcf86cd799439011",
  "encryptionKeyId": "507f1f77bcf86cd799439015",
  "fields": [
    {
      "id": "507f1f77bcf86cd799439019",
      "name": "Username",
      "type": "TEXT",
      "value": "admin",
      "isSecret": false
    },
    {
      "id": "507f1f77bcf86cd799439020",
      "name": "Password",
      "type": "PASSWORD",
      "value": "encrypted-ciphertext...",
      "isSecret": true
    }
  ]
}

Notes

For encrypted vaults, secret field values are RSA-encrypted ciphertext
Use GET /vault/encryption-key (AGENT-scoped API keys only) to retrieve the decryption key
Non-secret fields always return plaintext values

Archive Vault Item

Archives (soft-deletes) a vault item. The item is retained for audit purposes.

DELETE /api/v1/machine/vault/:vaultId/items/:itemId

Path Parameters

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

Response

Success (204 No Content)

No response body.

Get Project Environment Variables

Returns all vault item fields across all vaults associated with a project as a flat key-value map.

GET /api/v1/machine/vault/env/:projectId

Path Parameters

Parameter	Type	Required	Description
`projectId`	string	Yes	The unique identifier of the project

Response

Success (200 OK)

{
  "env": {
    "PRODUCTION_DB_USERNAME": "admin",
    "PRODUCTION_DB_PASSWORD": "s3cret",
    "AWS_CREDENTIALS_ACCESS_KEY": "AKIA..."
  },
  "projectId": "507f1f77bcf86cd799439014",
  "count": 3
}

Notes

Keys are formatted as SCREAMING_SNAKE_CASE: VAULT_ITEM_NAME_FIELD_NAME
Example: vault item "Production DB" with field "Password" becomes PRODUCTION_DB_PASSWORD

Get Agent Encryption Key

Returns the agent's RSA key pair for decrypting vault item secrets. Only available for AGENT-scoped API keys.

GET /api/v1/machine/vault/encryption-key

Response

Success (200 OK)

{
  "encryptionKeyId": "507f1f77bcf86cd799439015",
  "privateKey": "-----BEGIN PRIVATE KEY-----\n...",
  "publicKey": "-----BEGIN PUBLIC KEY-----\n..."
}

Notes

Requires an AGENT-scoped API key
The private key is envelope-encrypted (AES-256-GCM with KEK) at rest

DNS Record Types

The following DNS record types may be returned by the API:

A Record

Maps a domain to an IPv4 address.

{
  "type": "A",
  "name": "@",
  "value": "192.168.1.1",
  "ttl": 300
}

AAAA Record

Maps a domain to an IPv6 address.

{
  "type": "AAAA",
  "name": "@",
  "value": "2001:0db8:85a3:0000:0000:8a2e:0370:7334",
  "ttl": 300
}

CNAME Record

Creates an alias from one domain to another.

{
  "type": "CNAME",
  "name": "www",
  "value": "example.com.",
  "ttl": 300
}

MX Record

Specifies mail servers for the domain. Lower mxPref values indicate higher priority.

{
  "type": "MX",
  "name": "@",
  "value": "mail.example.com.",
  "ttl": 300,
  "mxPref": 10
}

TXT Record

Contains arbitrary text data, commonly used for SPF, DKIM, and domain verification.

{
  "type": "TXT",
  "name": "@",
  "value": "v=spf1 include:_spf.google.com ~all",
  "ttl": 300
}

NS Record

Specifies authoritative nameservers for the domain.

{
  "type": "NS",
  "name": "@",
  "value": "ns1.example.com.",
  "ttl": 86400
}

Pagination

Currently, endpoints return all results in a single response. Future endpoints may support pagination with the following format:

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 50,
    "total": 150,
    "totalPages": 3
  }
}

Query parameters for paginated endpoints:

Parameter	Type	Default	Description
`page`	number	1	Page number (1-indexed)
`limit`	number	50	Number of items per page (max 100)

Changelog

v1.3.0 (March 2026)

Added Vault Manager API with full vault CRUD:
- POST /vault — Create encrypted vault
- GET /vault — List vaults (with optional project filter)
- GET /vault/:vaultId — Get vault detail
- DELETE /vault/:vaultId — Archive vault
- POST /vault/:vaultId/items — Create vault item
- GET /vault/:vaultId/items — List vault items
- GET /vault/:vaultId/items/:itemId — Get vault item detail
- DELETE /vault/:vaultId/items/:itemId — Archive vault item
- GET /vault/env/:projectId — Get project environment variables
- GET /vault/encryption-key — Get agent encryption key

v1.2.0 (January 2026)

Added POST /domain-manager/dns-records endpoint for adding DNS records

v1.1.0 (January 2026)

Added GET /project/:id endpoint for project details

v1.0.0 (January 2026)

Initial release
Added GET /domain-manager/dns-records endpoint