fix(docs): added new api documentation, updated current state

[tbogosavljevic]

📝 Description

Our public API documentation was out of date in a few places. This PR updates docs/docs/reference/api.md to better match the current behavior of the Semaphor API.

This includes:

• adding public endpoints that were available but missing from the docs, including:
  • POST /api/v1alpha/projects to create a project
  • GET /api/v1alpha/projects to list projects
  • GET /api/v1alpha/jobs to list jobs
  • GET /api/v1alpha/jobs/:job_id/debug_ssh_key to fetch a debug SSH key for a running debug job
  • POST /api/v1alpha/jobs/:job_id/debug to start a debug job
  • GET /api/v1alpha/dashboards to list dashboards
  • GET /api/v1alpha/dashboards/:id_or_name to describe a dashboard
  • GET /api/v1alpha/notifications to list notifications
  • GET /api/v1alpha/notifications/:notification_id_or_name to describe a notification
  • GET /api/v1beta/secrets to list organization secrets
  • GET /api/v1beta/secrets/:secret_id_or_name to describe an organization secret
  • GET /api/v1/projects/:project_id_or_name/secrets to list project secrets
  • GET /api/v1/projects/:project_id_or_name/secrets/:secret_id_or_name to describe a project secret
  • POST /api/v1/artifacts to generate signed artifact URLs
• correcting stale response examples based on live API testing
• fixing request examples where the documented payload or headers did not match the current AP
• clarifying feature-gated or credential-gated behavior, such as self-hosted agents

PLEASE NOTE: I have tested each of the endpoints to get the data. For some endpoints (mostly the new ones), I deemed it better to include a "request payload" instead of the parameters, since some of them were a bit more complex, and I was unsure how to structure the parameters.

✅ Checklist

• I have tested this change
• This change requires documentation update

[tbogosavljevic]

This is not actually enforced by API it seems, so I removed it.

[tbogosavljevic]

I have not figured out:

• Self hosted agents API
• Promotions API was not verified
• Triggering tasks API was not verified

[tbogosavljevic]

@dexyk I add the changes about the artifacts API documentation from main branch here: fix(docs): added new api documentation, updated current state to match api

If it looks well, please re-review and we can merge this PR in, thanks! 🙇