NetBox Custom Objects

Your knowledge of Custom Objects may be outdated. Field types, relationship options, and API behavior evolve between plugin releases. Prefer retrieval over pre-trained knowledge.

Retrieval Sources

FIRST: Verify Connectivity

Confirm the Custom Objects plugin is installed:

curl -s -H "Authorization: Bearer $NETBOX_TOKEN" "$NETBOX_URL/api/plugins/custom-objects/custom-object-types/" | python -m json.tool

If you get 404, the plugin is not installed. If 403, your token needs custom_objects permissions.

Version note: this skill targets plugin v0.5.x (latest v0.5.1), which requires NetBox 4.5.2+ (through 4.6.x). v0.5 changed several behaviors vs v0.4.x — cross-COT references, API validation, and branching — these are flagged inline below.

Extend the NetBox data model without writing code. Custom Objects let administrators define new object types with typed fields, validation rules, and relationships — all through the UI or API.

When to Use This Skill

• Creating new object types in NetBox (e.g., DHCP Scopes, Contracts, Applications)
• Adding fields to custom object types (text, numeric, object references, etc.)
• Building integrations that create or consume custom objects via API
• Automating custom object type provisioning in scripts or CI/CD
• Querying linked objects (reverse lookups from core objects to custom objects)

Quick Reference

Core Concepts

API Endpoints

Field Types (14)

Creating a Custom Object Type

Step 1: Create the Type

POST /api/plugins/custom-objects/custom-object-types/

{
  "name": "dhcp_scope",
  "slug": "dhcp-scopes",
  "description": "DHCP address scopes",
  "verbose_name": "DHCP Scope",
  "verbose_name_plural": "DHCP Scopes",
  "group_name": "IPAM Extensions"
}

Naming rules:

• name: lowercase alphanumeric + underscores only. No double underscores. Must be unique.
• slug: URL-safe identifier. Used in API endpoint path.
• group_name: Optional. Groups this type with others in the sidebar navigation.

Step 2: Add Fields

POST /api/plugins/custom-objects/custom-object-type-fields/

{
  "custom_object_type": 1,
  "name": "scope_name",
  "label": "Scope Name",
  "type": "text",
  "required": true,
  "unique": true,
  "primary": true,
  "validation_regex": "^[a-zA-Z0-9_-]+$"
}

Key field properties:

Step 3: Create Instances

POST /api/plugins/custom-objects/dhcp-scopes/

{
  "scope_name": "office-floor-2",
  "ip_range": 5,
  "vlan": 100
}

The endpoint path uses the COT's slug (not name).

Object Reference Fields

Reference core NetBox objects or other custom objects using object and multiobject fields.

Referencing Core Objects

{
  "custom_object_type": 1,
  "name": "site",
  "label": "Site",
  "type": "object",
  "app_label": "dcim",
  "model": "site"
}

Common app_label.model combinations:

• dcim.device, dcim.site, dcim.rack, dcim.interface
• ipam.prefix, ipam.ipaddress, ipam.vlan, ipam.iprange
• tenancy.tenant, circuits.circuit, virtualization.virtualmachine

Referencing Other Custom Objects

Set app_label to "custom-objects" and model to the target COT's slug:

{
  "custom_object_type": 2,
  "name": "parent_scope",
  "label": "Parent Scope",
  "type": "object",
  "app_label": "custom-objects",
  "model": "dhcp-scopes"
}

Plugin v0.5+: the "custom-objects" + slug form is the supported way to reference another COT. (Older builds required an internal table{id}model name; do not use that against v0.5+.)

Self-referential fields (a COT pointing to itself) are allowed. Circular references between different COTs are detected and blocked.

Polymorphic Reference Fields

Plugin v0.5+: an object/multiobject field can reference multiple object types. Set ispolymorphic: true and provide the allowed types via relatedobjecttypesinput instead of app_label/model:

{
  "custom_object_type": 9,
  "name": "linked_resource",
  "label": "Linked Resource",
  "type": "object",
  "is_polymorphic": true,
  "related_object_types_input": [
    {"app_label": "dcim", "model": "device"},
    {"app_label": "custom-objects", "model": "servers"}
  ]
}

When writing an instance value for a polymorphic field, pass a dict identifying the type and object: {"applabel": "dcim", "model": "device", "objectid": 7} (contenttypeid and id are accepted aliases). The is_polymorphic flag and allowed types are immutable after the field is created.

Object-Deletion Behavior

Plugin v0.5+: object fields take an ondeletebehavior of "setnull" (default), "cascade", or "protect", controlling what happens to the custom object when a referenced object is deleted. Use relatedname to set the reverse-accessor name for ORM lookups.

Filtering Object Selections

Narrow the available choices using relatedobjectfilter:

{
  "custom_object_type": 1,
  "name": "active_device",
  "label": "Active Device",
  "type": "object",
  "app_label": "dcim",
  "model": "device",
  "related_object_filter": {"status": "active"}
}

Linked Objects (Reverse Lookups)

Find all custom objects that reference a given core object:

GET /api/plugins/custom-objects/linked-objects/?object_type=dcim.device&object_id=42

Response:

{
  "count": 2,
  "results": [
    {
      "custom_object_type": {"id": 1, "name": "Server", "slug": "servers"},
      "field_name": "primary_device",
      "object": {"id": 7, "display": "web-server-01", "url": "..."}
    }
  ]
}

Both objecttype and objectid are required parameters.

Programmatic Access (Scripts & Plugins)

Use custom objects in NetBox custom scripts or plugins:

from netbox_custom_objects.models import CustomObjectType

# Get the model class
cot = CustomObjectType.objects.get(name="dhcp_scope")
DHCPScope = cot.get_model()

# Query like any Django model
scopes = DHCPScope.objects.all()
scope = DHCPScope.objects.filter(scope_name="office-floor-2").first()
print(scope.scope_name, scope.site)

The generated model supports the full Django ORM (filter, create, update, delete, annotations, aggregations).

Branching Compatibility

Custom Objects is compatible with NetBox Branching but with limitations. The two layers behave differently — don't conflate them:

• Type and field definitions (COT/COTF): writable while a branch is active, but changes apply directly to main — they do not appear in the branch diff or "Changes Ahead" view.
• Custom object instances: writes on a branch are disallowed (plugin v0.5+). In an active branch you can still read existing instances, but you cannot create, edit, or delete custom objects until the branch is merged/exited. (Do not assume instance writes silently land on main — they are rejected.)

To move COT/COTF schemas between instances or promote branch-developed schemas, use the portable schema export/apply feature rather than editing on a branch.

Required configuration when using with Branching:

PLUGINS_CONFIG = {
    'netbox_branching': {
        'exempt_models': [
            'netbox_custom_objects.customobjecttype',
            'netbox_custom_objects.customobjecttypefield',
        ],
    },
}

Inherited NetBox Features

Every custom object automatically gets:

• Tags, bookmarks, journaling, change logging
• List views, detail views, import/export
• Search (configurable weight per field)
• Event rules and notifications
• Custom links, cloning
• REST API with filtering and pagination
• Object permissions

Important Constraints

1. Deletion is destructive: Deleting a COT drops the entire database table. Deleting a COTF drops the column. Both are irreversible.
2. No GraphQL support yet — REST API only.
3. No bulk create — the instance API does not accept arrays. Create instances one at a time.
4. Field validation is enforced on API writes (plugin v0.5+): required, validationregex, validationminimum, and validationmaximum are now applied on REST API writes as well as the UI. NetBox's CUSTOMVALIDATORS setting is also honored — key it as netboxcustomobjects.<cot-slug>. (In v0.4.x these were UI-only; do not rely on that against v0.5+.)
5. Max types: Default limit of 50 custom object types (configurable via maxcustomobject_types).
6. Reserved field names: ~30 names are reserved (e.g., id, tags, created, last_updated, model, objects, pk, save, delete). The API returns a clear error if you try to use one.
7. Uniqueness constraints: Cannot be enforced on boolean or multiobject fields.
8. Name format: COT names and COTF names must be lowercase alphanumeric with underscores. No double underscores.
9. Cross-COT references use the COT slug (plugin v0.5+): applabel: "custom-objects" + model: "<target-slug>". Polymorphic fields reference multiple types via relatedobjecttypesinput.
10. Minimum NetBox version: plugin v0.5.x requires NetBox 4.5.2+ (through 4.6.x). Installs on 4.4.x / 4.5.0 / 4.5.1 are not supported by current releases.

Common Patterns

See reference files for detailed patterns:

• [references/modeling-patterns.md](references/modeling-patterns.md) — Design patterns for common use cases
• [references/field-type-guide.md](references/field-type-guide.md) — Detailed field configuration and validation
• [references/api-workflow.md](references/api-workflow.md) — Complete API workflow with examples

Related Skills

• [netbox-data-modeling](../netbox-data-modeling/) — Core NetBox data model (use before creating custom objects to check if a built-in model already fits)
• [netbox-api-integration](../netbox-api-integration/) — REST API patterns that apply to custom object endpoints
• [netbox-plugin-development](../netbox-plugin-development/) — When custom objects aren't enough and you need a full plugin
• [netbox-branching](../netbox-branching/) — Branch compatibility considerations
• [netbox-custom-scripts](../netbox-custom-scripts/) — Using custom objects in scripts

Resources

• GitHub Repository
• API Documentation
• Compatibility Matrix