docs: add Projects API guidance for common reference gaps

[VeronicaSnyk]

Docs gap fix

Gap (shared underlying issue): The Projects REST API reference page contained only OpenAPI spec blocks with no prose — users could not find query parameter usage, tags filter format, deactivation/move procedures, permission requirements, or how to reach the Issues endpoint from a project context.

Source questions (cluster):

• "What query parameters does GET /orgs/{org_id}/projects support for status, target_id, target_reference, tags, and limit, how is the tags filter formatted, and can a project be deactivated via PATCH?"
• "What is the request body format for moving a project?"
• "What permissions or scopes are required for GET /orgs/{org_id}/projects, and does meta.latest_issue_counts require extra permissions?"
• "How do I set a Snyk project owner via API, including the endpoint and request body?"
• "Does the Issues API pull from inactive projects?"
• "What REST API endpoint lists issues for a Snyk project, including the path and parameters?"
• "What query parameters does GET /orgs/{org_id}/projects support, including status, target_id, target_reference, tags, and limit, how is the tags filter formatted, and can a project be deactivated via REST PATCH or only with the v1 deactivate endpoint?"

Topic: developer-tools (API reference)
Answer status: not answered (0%)
Fix type: create (new prose sections on existing reference page)
Origin: GitBook AI Insights — brief-0.json, cluster endpoint:projects, priority score 54, last asked 2026-07-14

What changed

• developer-tools/snyk-api/reference/projects.md: added a permissions summary table, tags filter format guide, limit constraints note, project owner PATCH example, v1 deactivate procedure, v1 move procedure, and Issues API cross-reference.

Sources of truth used

• GET /orgs/{org_id}/projects query params (target_id, target_reference, tags, limit schema, meta.latest_issue_counts, business_criticality enums, environment enums, lifecycle enums) — rest-spec.json, path /orgs/{org_id}/projects, GET operation
• PATCH /orgs/{org_id}/projects/{project_id} permissions and request body (attributes: business_criticality, environment, lifecycle, tags, test_frequency; relationships.owner.data: type "user", id uuid|null) — rest-spec.json, path /orgs/{org_id}/projects/{project_id}, PATCH operation
• POST /org/{orgId}/project/{projectId}/deactivate — no request body; effects: disables PR tests, Fix PRs, recurring tests, removes webhooks — v1-api-spec.yaml, lines 2401–2447
• PUT /org/{orgId}/project/{projectId}/move — body: {targetOrgId: string}, group admin permissions required, historical data does not move — v1-api-spec.yaml, lines 3548–3602
• GET /orgs/{org_id}/issues — scan_item_id, scan_item_type query params; include_deactivated param; required permissions include View Project history — rest-spec.json, path /orgs/{org_id}/issues
• Owner field: "Set to null to remove all ownership. User must be a member of the same organization." — v1-api-spec.yaml, line 17289

Needs human input

• status filter on GET /orgs/{org_id}/projects — users asked about this in seven questions, but no status query parameter was found in rest-spec.json for this endpoint. Confirm whether it exists under a different name, or confirm it is absent (in which case the note pointing to v1 deactivate is the correct answer).
• include_deactivated on issues vs. project activation — rest-spec.json describes this param as "include disabled issues in results" (issue status), not project activation status. Confirm whether inactive/deactivated projects are excluded from GET /orgs/{org_id}/issues by default and whether this param is the correct lever.

Reviewer checklist

• Answers the original question
• Every reference fact is cited / no invented values
• Style-guide skill applied
• Links valid, no orphaned page

label: source:gap-detected