Workday Recruiting agentDefinition API

openapi: 3.1.0
info:
  title: Workday Recruiting REST Applicants agentDefinition API
  description: RESTful API for managing recruiting operations within Workday Human Capital Management. Provides programmatic access to job requisitions, candidates, job applications, job postings, interviews, and hiring workflows. Supports integration with external talent management and applicant tracking systems using OAuth 2.0 authentication and JSON data format.
  version: v41.2
  contact:
    name: Workday Support
    url: https://www.workday.com/en-us/services/support.html
  termsOfService: https://www.workday.com/en-us/legal.html
  x-generated-from: documentation
  x-source-url: https://community.workday.com/sites/default/files/file-hosting/restapi/index.html
  x-last-validated: '2026-05-03'
servers:
- url: https://{tenant}.workday.com/ccx/api/recruiting/v41.2
  description: Workday Recruiting Production
  variables:
    tenant:
      description: Workday tenant identifier (e.g., wd2-impl-services1)
      default: your-tenant
security:
- oauth2: []
tags:
- name: agentDefinition
  description: To view and maintain Agent Definitions with the Agent System of Record.
  x-workday-confidence-level: Exotic
paths:
  /agentDefinition:
    get:
      tags:
      - agentDefinition
      summary: This operation returns the specific Agent Definition including Skills and certain Tools used in those Skills.
      description: 'This operation returns the specific Agent Definition including Skills and certain Tools used in those Skills. Each definition can contain many Skills, and in those Skills they *may* contain Tools based on the Invocation / Execution Type. Generally REST APIs will be listed here.


        <b>Secured by:</b> Development, Setup: Agents'
      responses:
        '200':
          description: Successful response. A successful response can return no matched data.
          content:
            application/json:
              schema:
                type: object
                properties:
                  total:
                    type: integer
                    format: int32
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/agentCardAndTools_a5967cb3b88b10001f7a6900b0d90000'
        '400':
          description: Invalid request. (https://community.workday.com/rest/error-messages)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VALIDATION_ERROR_MODEL_REFERENCE'
        '401':
          description: 'Unauthorized: Missing or invalid credentials. (https://community.workday.com/rest/error-messages)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VALIDATION_ERROR_MODEL_REFERENCE'
        '403':
          description: User has insufficient permissions. (https://community.workday.com/rest/error-messages)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VALIDATION_ERROR_MODEL_REFERENCE'
        '404':
          description: Resource not found. (https://community.workday.com/rest/error-messages)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VALIDATION_ERROR_MODEL_REFERENCE'
        default:
          description: An error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ERROR_MODEL_REFERENCE'
      x-workday-confidence-level: Exotic
      x-workday-internal-try-enabled: 'false'
    post:
      tags:
      - agentDefinition
      summary: Based on the A2A Agent Card specification, this REST operation allows you to create an Agent Definition in Workday.
      description: 'Based on the A2A Agent Card specification, this REST operation allows you to create an Agent Definition in Workday, while also highlighting the specific Workday APIs/Resources that the Agent is allowed access to. It will update an existing instance IF one already exists with the same *name*, *provider organization*, and *version*.


        <b>Secured by:</b> Development, Setup: Agents'
      requestBody:
        content:
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/agentCardAndTools_a5967cb3b88b10001f7a6900b0d90000'
      responses:
        '201':
          description: Resource created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/agentCardAndTools_a5967cb3b88b10001f7a6900b0d90000'
        '400':
          description: 'Invalid request. (https://community.workday.com/rest/error-messages)

            Error Code | Validation Message

            --- | ---

            A161 | You can''t select Workday as the agent platform for third-party agents. Select a different platform.

            A2849 | Create an agent ID sequence generator using the Edit Tenant Setup - System task before registering agents.

            A3015 | The External Agent ID must be unique for Agent Definitions with the same Provider.'
          content: {}
        '401':
          description: 'Unauthorized: Missing or invalid credentials. (https://community.workday.com/rest/error-messages)'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VALIDATION_ERROR_MODEL_REFERENCE'
        '403':
          description: User has insufficient permissions. (https://community.workday.com/rest/error-messages)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VALIDATION_ERROR_MODEL_REFERENCE'
        '404':
          description: Resource not found. (https://community.workday.com/rest/error-messages)
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VALIDATION_ERROR_MODEL_REFERENCE'
        default:
          description: An error occurred.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ERROR_MODEL_REFERENCE'
      x-workday-confidence-level: Exotic
      x-workday-internal-try-enabled: 'false'
components:
  schemas:
    agentSkillTag_71f49719113310002d130aa875ca0000:
      allOf:
      - required:
        - tag
        type: object
        properties:
          tag:
            type: string
            description: Will be used by the client as a hint to understand how the skill can be used.
            example: '[{"tag":"cooking"}, {"tag":"customer support"}]'
            x-workday-type: Text
    defaultOutputModes_71f497191133100013c9a17716d50001:
      allOf:
      - $ref: '#/components/schemas/mimeType_71f4971911331000139693324a560000'
      - type: object
        properties:
          id:
            type: string
            description: The id for Mime Type (Derived)
    agentCapabilites_799da24a09dd10000e37766515630000:
      allOf:
      - type: object
        properties:
          pushNotifications:
            type: boolean
            description: true if the agent can notify updates to client.
            example: true
            x-workday-type: Boolean
          stateTransitionHistory:
            type: boolean
            description: true if the agent exposes status change history for tasks.
            example: true
            x-workday-type: Boolean
          streaming:
            type: boolean
            description: true if the agent supports SSE.
            example: true
            x-workday-type: Boolean
    agentSkill_881e3f87712810000d0bf06dae650000:
      allOf:
      - required:
        - description
        - id
        - name
        type: object
        properties:
          tags:
            type: array
            description: Set of tagwords describing classes of capabilities for this specific skill.
            items:
              $ref: '#/components/schemas/tags_71f49719113310002d148ce3f5370002'
            x-workday-type: Multi-instance
          inputModes:
            type: array
            description: The set of interaction modes that the skill supports (if different than the default).
            items:
              $ref: '#/components/schemas/inputModes_71f49719113310002d148ce3f5370001'
            x-workday-type: Multi-instance
          outputModes:
            type: array
            description: Supported media types for output.
            items:
              $ref: '#/components/schemas/outputModes_71f49719113310002d148ce3f5370000'
            x-workday-type: Multi-instance
          description:
            type: string
            description: Description of the skill - will be used by the client or a human as a hint to understand what the skill does.
            example: This skill analyzes many financial documents in the boundary for the supervisory org.
            x-workday-type: Text
          id:
            type: string
            description: Unique identifier for the agent's skill.
            example: '1234'
            x-workday-type: Text
          name:
            type: string
            description: Human readable name of the skill.
            example: Financial Audit Analyzer
            x-workday-type: Text
    ERROR_MODEL_REFERENCE:
      required:
      - error
      type: object
      properties:
        error:
          type: string
          description: A description of the error
        code:
          type: string
          description: The code that corresponds to the error message. Use the error code to drive programmatic error-handling behavior. Don't use error message strings for this purpose because they are subject to change
        field:
          type: string
          description: The field related to the error
        path:
          type: string
          description: The path of the field related to the error
    agentPlatform_aa793a5c168d1000143f8b9f05c50000:
      allOf:
      - type: object
        properties:
          reference_id:
            type: string
            description: Reference ID for the Instance of Agent Platform
            example: Lorem ipsum dolor sit amet, cum choro singulis consectetuer ut, ubique iisque contentiones ex duo. Quo lorem etiam eu.
            x-workday-type: Text
          descriptor:
            type: string
            description: The display name of the instance
            example: Lorem ipsum dolor sit ame
          id:
            type: string
            description: Workday Id or Reference Id of the instance.
    INSTANCE_MODEL_REFERENCE:
      required:
      - id
      type: object
      properties:
        id:
          pattern: ^(([0-9a-f]{32})|(\S+=\S+))$
          type: string
          description: Workday Id or Reference Id of the instance.
        descriptor:
          type: string
          description: The display name of the instance
          readOnly: true
        href:
          type: string
          description: A link to the instance
          readOnly: true
    agentSkillResource_881e3f87712810000d1ba8a0a0510000:
      allOf:
      - type: object
        properties:
          workdayResources:
            type: array
            description: List of Workday Resources used by this agents skill.
            items:
              $ref: '#/components/schemas/workdayResources_881e3f877128100010fb617ba5260000'
            x-workday-type: Multi-instance
          skillId:
            type: string
            description: Unique identifier for the agent's skill.
            example: Lorem ipsum dolor sit amet, cum choro singulis consectetuer ut, ubique iisque contentiones ex duo. Quo lorem etiam eu.
            x-workday-type: Text
          executionMode:
            $ref: '#/components/schemas/executionMode_d785eba56e9c10003761356522e00000'
    capabilities_799da24a09dd10000e3a424ec7340000:
      description: Optional capabilities supported by the agent.
      allOf:
      - $ref: '#/components/schemas/agentCapabilites_799da24a09dd10000e37766515630000'
      - type: object
    agent_resource_2e69afd4e86c10001ad2755763bc0000:
      description: The Workday Resource for this Tools if applicable.
      allOf:
      - $ref: '#/components/schemas/workdayResource_2e69afd4e86c10001fae2831c6da0000'
      - type: object
    VALIDATION_ERROR_MODEL_REFERENCE:
      allOf:
      - required:
        - error
        type: object
        properties:
          error:
            type: string
            description: A description of the error
          errors:
            type: array
            description: An array of validation errors
            items:
              $ref: '#/components/schemas/ERROR_MODEL_REFERENCE'
    provider_799da24a09dd10000b827743c6f40000:
      description: The service provider of the agent
      allOf:
      - $ref: '#/components/schemas/INSTANCE_MODEL_REFERENCE'
      - type: object
    skills_881e3f87712810000d1cfd55ee0d0000:
      allOf:
      - $ref: '#/components/schemas/agentSkill_881e3f87712810000d0bf06dae650000'
      - type: object
        properties:
          id:
            type: string
            description: The id for Agent Definition Skill (Derived)
    mimeType_71f4971911331000139693324a560000:
      allOf:
      - type: object
        properties:
          type:
            maxLength: 80
            type: string
            description: Supported media type.
            example: Lorem ipsum dolor sit amet, cum choro singulis consectetuer ut, ubique iisque contentiones ex duo. Quo lorem etiam eu.
            x-workday-type: Text
    workdayConfig_881e3f87712810000d1cfd55ee0d0001:
      allOf:
      - $ref: '#/components/schemas/agentSkillResource_881e3f87712810000d1ba8a0a0510000'
      - type: object
        properties:
          id:
            type: string
            description: The id for Agent Definition Skill (Derived)
    tools_a81e152b86021000158c36e9bbdc0001:
      allOf:
      - $ref: '#/components/schemas/workdayTool_a81e152b86021000158aa15c84900000'
      - type: object
        properties:
          id:
            type: string
            description: The id for Secured (All) (Derived)
    workdayTool_a81e152b86021000158aa15c84900000:
      allOf:
      - type: object
        properties:
          id:
            type: string
            description: Workday Id or Reference Id of the instance.
          descriptor:
            type: string
            description: The display name of the instance
            example: Lorem ipsum dolor sit ame
    workdayResources_881e3f877128100010fb617ba5260000:
      allOf:
      - $ref: '#/components/schemas/skillTools_881e3f877128100010f2ba3820a20000'
      - type: object
        properties:
          id:
            type: string
            description: The id for Agent Tool (Derived)
    executionMode_d785eba56e9c10003761356522e00000:
      description: The Execution Mode this Skill is operating in. Either Ambient, or Delegate.
      allOf:
      - $ref: '#/components/schemas/INSTANCE_MODEL_REFERENCE'
      - type: object
    inputModes_71f49719113310002d148ce3f5370001:
      allOf:
      - $ref: '#/components/schemas/mimeType_71f4971911331000139693324a560000'
      - type: object
        properties:
          id:
            type: string
            description: The id for Mime Type (Derived)
    skillTools_881e3f877128100010f2ba3820a20000:
      allOf:
      - required:
        - description
        - tool_name
        type: object
        properties:
          description:
            type: string
            description: Description of the Operation.
            example: Lorem ipsum dolor sit amet, cum choro singulis consectetuer ut, ubique iisque contentiones ex duo. Quo lorem etiam eu.
            x-workday-type: Text
            x-workday-confidence-level: Exotic
          agent_resource:
            $ref: '#/components/schemas/agent_resource_2e69afd4e86c10001ad2755763bc0000'
          tool_name:
            type: string
            description: Name of the Operation.
            example: Lorem ipsum dolor sit amet, cum choro singulis consectetuer ut, ubique iisque contentiones ex duo. Quo lorem etiam eu.
            x-workday-type: Text
            x-workday-confidence-level: Exotic
          tools:
            type: array
            description: Any related Workday Securable Items used by the Workday Resource.
            items:
              $ref: '#/components/schemas/tools_a81e152b86021000158c36e9bbdc0001'
            x-workday-type: Multi-instance
    defaultInputModes_71f497191133100013c9a17716d50000:
      allOf:
      - $ref: '#/components/schemas/mimeType_71f4971911331000139693324a560000'
      - type: object
        properties:
          id:
            type: string
            description: The id for Mime Type (Derived)
    workdayResource_2e69afd4e86c10001fae2831c6da0000:
      allOf:
      - type: object
        properties:
          descriptor:
            type: string
            description: The display name of the instance
            example: Lorem ipsum dolor sit ame
          id:
            type: string
            description: The id for Agent Resource (Derived)
    outputModes_71f49719113310002d148ce3f5370000:
      allOf:
      - $ref: '#/components/schemas/mimeType_71f4971911331000139693324a560000'
      - type: object
        properties:
          id:
            type: string
            description: The id for Mime Type (Derived)
    tags_71f49719113310002d148ce3f5370002:
      allOf:
      - $ref: '#/components/schemas/agentSkillTag_71f49719113310002d130aa875ca0000'
      - type: object
        properties:
          id:
            type: string
            description: The id for Agent Definition Skill Tag (Derived)
    platform_ca94626efa9010003262e35486130000:
      description: The platform of the agent.
      allOf:
      - $ref: '#/components/schemas/agentPlatform_aa793a5c168d1000143f8b9f05c50000'
      - type: object
    agentCardAndTools_a5967cb3b88b10001f7a6900b0d90000:
      allOf:
      - required:
        - description
        - name
        - skills
        - url
        - version
        type: object
        properties:
          overview:
            type: string
            description: The overview message for the agent.
            example: Lorem ipsum dolor sit amet, cum choro singulis consectetuer ut, ubique iisque contentiones ex duo. Quo lorem etiam eu.
            x-workday-type: Text
            x-workday-confidence-level: Exotic
          defaultInputModes:
            type: array
            description: The set of interaction modes that the agent supports across all skills. This can be overridden per-skill. Supported media types for input.
            items:
              $ref: '#/components/schemas/defaultInputModes_71f497191133100013c9a17716d50000'
            x-workday-type: Multi-instance
          id:
            type: string
            description: Agent Definition ID. Used to link Agent Versions.
            example: Lorem ipsum dolor sit amet, cum choro singulis consectetuer ut, ubique iisque contentiones ex duo. Quo lorem etiam eu.
            x-workday-type: Text
          version:
            type: string
            description: The version of the agent - format is up to the provider.
            example: 1.0.0
            x-workday-type: Text
          documentationUrl:
            type: string
            description: A URL to documentation for the agent.
            example: https://agent.company.com/agent1/doc
            x-workday-type: Text
          capabilities:
            $ref: '#/components/schemas/capabilities_799da24a09dd10000e3a424ec7340000'
          externalTenantID:
            type: string
            description: Used to identify the tenant for agents not owned or managed by Workday.
            example: Lorem ipsum dolor sit amet, cum choro singulis consectetuer ut, ubique iisque contentiones ex duo. Quo lorem etiam eu.
            x-workday-type: Text
            x-workday-confidence-level: Exotic
          externalAgentID:
            type: string
            description: External system’s identifier for agents not owned or managed by Workday.
            example: Lorem ipsum dolor sit amet, cum choro singulis consectetuer ut, ubique iisque contentiones ex duo. Quo lorem etiam eu.
            x-workday-type: Text
            x-workday-confidence-level: Exotic
          provider:
            $ref: '#/components/schemas/provider_799da24a09dd10000b827743c6f40000'
          iconUrl:
            type: string
            description: A URL to an icon for the agent.
            example: https://cdn1.iconfinder.com/data/icons/material-design-icons-light/24/link-variant-512.png
            x-workday-type: Text
          workdayConfig:
            type: array
            description: Identify Workday Resources to be used in Agent Skills.
            items:
              $ref: '#/components/schemas/workdayConfig_881e3f87712810000d1cfd55ee0d0001'
            x-workday-type: Multi-instance
          skills:
            type: array
            description: Skills are a unit of capability that an agent can perform.
            items:
              $ref: '#/components/schemas/skills_881e3f87712810000d1cfd55ee0d0000'
            x-workday-type: Multi-instance
          description:
            type: string
            description: A human-readable description of the agent. Used to assist users and other agents in understanding what the agent can do.
            example: This Financial Audit Agent acts as a safeguard, offering an independent review that instills confidence in financial information.
            x-workday-type: Text
          url:
            type: string
            description: A URL to the address the agent is hosted at.
            example: https://example.com/agent/finance
            x-workday-type: Text
          name:
            type: string
            description: Human readable name of the agent.
            example: Financial Audit Agent
            x-workday-type: Text
          supportsAuthenticatedExtendedCard:
            type: boolean
            description: true if the agent supports providing an extended agent card when the user is authenticated. Defaults to false if not specified.
            example: true
            x-workday-type: Boolean
          platform:
            $ref: '#/components/schemas/platform_ca94626efa9010003262e35486130000'
          defaultOutputModes:
            type: array
            description: Supported media types for output.
            items:
              $ref: '#/components/schemas/defaultOutputModes_71f497191133100013c9a17716d50001'
            x-workday-type: Multi-instance
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 authentication. Register an API client in Workday, grant recruiting scopes, and obtain access tokens.
      flows:
        authorizationCode:
          authorizationUrl: https://{tenant}.workday.com/authorize
          tokenUrl: https://{tenant}.workday.com/ccx/oauth2/token
          scopes:
            recruiting:read: Read recruiting data
            recruiting:write: Modify recruiting data
externalDocs:
  description: Workday Recruiting REST API Documentation
  url: https://community.workday.com/sites/default/files/file-hosting/restapi/index.html