{
  "connector": "servicenow",
  "label": "ServiceNow",
  "vendor_docs": "https://developer.servicenow.com/dev.do#!/reference/api/latest/rest/",
  "summary": "A ServiceNow instance that answers the Table, CMDB Instance, Aggregate, Service Catalog, Knowledge and Attachment APIs `pysnc` and `pysnow` call, plus an MCP server.",
  "surfaces": [
    {
      "kind": "REST",
      "path": "/api/now/table",
      "notes": "Table API, also under `/api/now/v1/table` and `/api/now/v2/table`"
    },
    {
      "kind": "REST",
      "path": "/api/now/cmdb",
      "notes": "CMDB Instance API, read-only; Aggregate API under `/api/now/stats`"
    },
    {
      "kind": "REST",
      "path": "/api/sn_sc/servicecatalog",
      "notes": "Service Catalog API"
    },
    {
      "kind": "REST",
      "path": "/api/sn_km_api/knowledge",
      "notes": "Knowledge API"
    },
    {
      "kind": "REST",
      "path": "/api/now/attachment",
      "notes": "Attachment API"
    },
    {
      "kind": "OAuth",
      "path": "/oauth_token.do",
      "notes": "`password`, `refresh_token` and `client_credentials` grants"
    },
    {
      "kind": "MCP",
      "path": "/mcp",
      "notes": "table tools and the `servicenow-mcp` tool set"
    }
  ],
  "api_versions": [
    "Table API (unversioned, v1, v2)",
    "CMDB Instance API (unversioned, v1)"
  ],
  "supported": [
    {
      "item": "Encoded queries in `sysparm_query` (`^`, `^OR`, `^NQ`, `LIKE`, `STARTSWITH`, `IN`, `ISEMPTY`, `BETWEEN`, `ORDERBY`, dot-walks and `javascript:gs.*` date helpers)"
    },
    {
      "item": "`sysparm_fields`, `sysparm_limit`, `sysparm_offset`, `sysparm_display_value` and `sysparm_exclude_reference_link`, with `X-Total-Count` and a `Link` header on lists"
    },
    {
      "item": "ServiceNow's `{\"result\": ...}` responses and `{\"error\": {\"message\", \"detail\"}, \"status\": \"failure\"}` errors"
    },
    {
      "item": "Basic and bearer auth, and OAuth token exchange at `/oauth_token.do`"
    },
    {
      "item": "`pysnc` and `pysnow` against a live server"
    },
    {
      "item": "Aggregate API counts, averages, sums, min and max with `sysparm_group_by` and `sysparm_having`"
    },
    {
      "item": "Users, groups, CMDB, incidents, problems, changes, SLAs, Service Catalog requests, approvals and knowledge articles"
    }
  ],
  "unsupported": [
    {
      "item": "Tables outside the documented table list"
    },
    {
      "item": "CMDB Instance API writes; that API is read-only"
    }
  ],
  "differences": [
    {
      "scenario": "Unknown query conditions",
      "difference": "Conditions on unknown fields are ignored, as ServiceNow does, so the query returns rows instead of an error.",
      "guidance": "Do not expect a 400 for a misspelled field in `sysparm_query`."
    },
    {
      "scenario": "Writes on a self-run instance",
      "difference": "Client writes, through REST and MCP, are refused unless the host enables them.",
      "guidance": "Enable writes on the instance you run before testing create, update or delete."
    },
    {
      "scenario": "Attachment size",
      "difference": "An uploaded file is kept up to 1 MiB.",
      "guidance": "Do not test large attachments against the replica."
    },
    {
      "scenario": "Record ids",
      "difference": "`sys_id`s are deterministic 32-hex values, stable across runs.",
      "guidance": "Read ids from the API; do not hard-code ids from a real instance."
    },
    {
      "scenario": "Featured and most-viewed articles",
      "difference": "Knowledge articles are ranked by ticket links and `sys_view_count`.",
      "guidance": "Do not assert on a specific ranking order."
    }
  ],
  "faults_supported": [
    {
      "fault": "throttle",
      "behaviour": "429 `{\"error\": \"rate_limited\", \"message\": \"Too Many Requests\"}` with `Retry-After`"
    },
    {
      "fault": "fail_next",
      "behaviour": "The next N calls fail as `throttle` does, then clear"
    },
    {
      "fault": "quota_limit",
      "behaviour": "429 `{\"error\": \"quota_exceeded\"}` once the per-window quota is spent"
    },
    {
      "fault": "error_rate",
      "behaviour": "500 for the given fraction of calls"
    },
    {
      "fault": "latency_ms",
      "behaviour": "Fixed added latency on every data-plane request"
    }
  ]
}