Documentation | 2025.1

# Specs: Spec fields

## Get spec information

### Summary

Get spec file fields.

GET /api/v11/specs/{spec}/ fields

### Description

Get fields for a spec type.

Parameter | Description | Type | Parameter Type | Required
--- | --- | --- | --- | ---
spec | Spec type. Valid spec types and location in the Helix Core Server spec depot: branch: //spec/branch/ change: the change spec is not stored in the Helix Core Server spec depot client: //spec/client/ depot: //spec/depot/ group: //spec/group/ job: //spec/job/ label: //spec/label/ license: //spec/license.p4s protect: //spec/protect.p4s spec: //spec/spec/ stream: //spec/stream/ triggers: //spec/triggers.p4s typemap: //spec/typemap.p4s user: //spec/user/ | string | path | Yes
fields | Omitting the fields parameter or including the fields parameter with no fields specified, returns all of the fields in the spec including any custom fields. Limit the response to specific fields by including a list of comma-separated fields in the request. The fields available depend on the spec type requested. Invalid fields do not cause an error and are ignored. | array of strings | path | No

### Example usage

#### Fetch all fields for the job spec

Fetching all fields for the job spec

curl -u "username:ticket" "https://myswarm-url/api/v11/specs/job/fields"

Swarm responds with:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "job": {
          "Job": {
            "code": "101",
            "dataType": "word",
            "displayLength": "32",
            "fieldType": "required"
          },
          "Status": {
            "code": "102",
            "dataType": "select",
            "displayLength": "10",
            "fieldType": "required",
            "options": [
              "open",
              "suspended",
              "fixed",
              "closed"
            ],
            "default": "open"
          },
          "Created_by": {
            "code": "103",
            "dataType": "word",
            "displayLength": "32",
            "fieldType": "once",
            "default": "$user"
          },
          "Description": {
            "code": "105",
            "dataType": "text",
            "displayLength": "0",
            "fieldType": "required",
            "default": "$blank"
          },
          "Date_modified": {
            "code": "130",
            "dataType": "date",
            "displayLength": "20",
            "fieldType": "always",
            "default": "$now"
          }
        }
      }
    }

#### Limit results to job and status fields for the job spec

Limit the results to the job and status fields for the job spec.

curl -u "username:ticket" "https://myswarm-url/api/v11/specs/job/fields?fields=status,job"

Swarm responds with:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "job": {
          "Job": {
            "code": "101",
            "dataType": "word",
            "displayLength": "32",
            "fieldType": "required"
          },
          "Status": {
            "code": "102",
            "dataType": "select",
            "displayLength": "10",
            "fieldType": "required",
            "options": [
              "open",
              "suspended",
              "fixed",
              "closed"
            ],
            "default": "open"
          }
        }
      }
    }

#### Limit results to depot and type fields for the depot spec

Limit the results to the depot and type fields for the depot spec.

curl -u "username:ticket" "https://myswarm-url/api/v11/specs/depot/fields?fields=depot,type"

Swarm responds with:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "depot": {
          "Depot": {
            "code": "251",
            "dataType": "word",
            "displayLength": "32",
            "fieldType": "key"
          },
          "Type": {
            "code": "255",
            "dataType": "word",
            "displayLength": "10",
            "fieldType": "required"
          }
        }
      }
    }

#### Limit results to status and type fields for the change spec

Limit the results to the status and type fields for the change spec.

curl -u "username:ticket" "https://myswarm-url/api/v11/specs/change/fields?fields=status,type"

Swarm responds with:

    HTTP/1.1 200 OK

    {
      "error": null,
      "messages": [],
      "data": {
        "change": {
          "Status": {
            "code": "205",
            "dataType": "word",
            "displayLength": "10",
            "fieldType": "always",
            "order": "5",
            "position": "R"
          },
          "Type": {
            "code": "211",
            "dataType": "select",
            "displayLength": "10",
            "fieldType": "optional",
            "order": "6",
            "position": "L",
            "options": [
              "public",
              "restricted"
            ]
          }
        }
      }
    }

#### If a request fails

<error code>:

- 400 Unknown spec type requested
- 401 Insufficient permissions to fetch spec fields

    HTTP/1.1 <response error code>

    {
      "error": <error code>,
      "messages": [{
        "code" : "<code string>",
        "text" : "<error message>"
      }],
      "data" : null
    }

Your search for returned results