Second Shift Agents developer portal

Second Shift Agents exposes public discovery interfaces for people and AI agents, plus an organization-scoped Client API for approved customers. Public discovery does not grant client access. Client operations require the same verified organization, OAuth scopes, workflow grants, approval gates, idempotency controls, audit trail, and tenant isolation used by the human portal.

Start here

Public interfaces

The public Streamable HTTP MCP endpoint is POST /mcp. It supports initialize, ping, tools/list, and tools/call. Anonymous callers can use about_second_shift and can submit book_working_session; booking requests are stored for owner review and do not schedule, charge, or create automation without human confirmation. The public A2A JSON-RPC endpoint is POST /a2a/v1.

Client API access

The Client API begins at /api/v1/ and uses OAuth 2.0 Authorization Code with PKCE. Submit POST /api/v1/preflights to describe one workflow and authority model before provisioning. A preflight creates no account, credential, checkout session, charge, or operational action. After human verification, Second Shift provisions an organization-bound client with only the approved scopes. Read auth.md before integrating.

Private pilots may begin in a read-only introduction mode. The MCP cannot inspect local files, other agent conversations, browser history, email, or unrelated projects; it receives only arguments deliberately sent through an MCP tool call. Authenticated tool discovery is filtered to the active grant, and private-content submission remains unavailable until separately enabled for an agreed workflow and consent boundary.

Example requests

Describe one workflow before credentials or checkout exist:

POST /api/v1/preflights HTTP/1.1
Host: www.secondshiftagents.com
Content-Type: application/json

{
  "organizationName": "Example Company",
  "requesterName": "Avery Chen",
  "requesterEmail": "avery@example.com",
  "requesterKind": "human",
  "workflow": "Turn an approved purchase order into a booked shipment",
  "systems": "Email, ERP, carrier portal",
  "outcome": "Shipment booked with a reviewable bill of lading",
  "sampleInputs": "Purchase order and shipping instructions",
  "sampleOutputs": "Sales order, booking confirmation, bill of lading",
  "expectedVolume": "About 20 orders per week",
  "approvalPoints": "Human approval before carrier booking",
  "billingAuthorityAsserted": false
}

After provisioning, a client agent reads only its active organization and grants:

GET /api/v1/overview HTTP/1.1
Host: www.secondshiftagents.com
Authorization: Bearer <organization-scoped OAuth token>
Accept: application/json

Use the schemas and operation descriptions in openapi.json when generating function calls. A request body or parameter is documented only when the operation actually accepts that input; parameterless operations remain parameterless.

Anonymous evaluation is available at POST /api/v1/sandbox/preflights with workflow and outcome strings. It returns a synthetic response and performs no persistence or external effects. See /sandbox.

Errors, versions, and change policy

REST errors use RFC 9457 application/problem+json fields including type, title, status, detail, instance, and a stable code. The legacy nested error.code, error.message, and error.resolution fields remain for compatibility. Callers should branch on code. Authentication failures use 401 with WWW-Authenticate; insufficient scope uses 403; resources outside the active organization or grant return 404 without confirming existence.

API responses include the current structured RateLimit-Policy and RateLimit fields, compatibility X-RateLimit-* fields, and X-Request-ID. A 429 response also includes Retry-After.

Stable REST operations use the major-version /api/v1 prefix. Breaking contract changes require a new major path. Compatible additions may appear in the current version. The full deprecation and sunset contract is published at /api-versioning. No anonymous production Client API or self-serve production credential is offered.

Pricing is scoped to the real workflow and documented at /pricing. The public privacy notice is at /privacy.

Support

For integration questions, email agent@secondshiftagents.com. Do not send credentials, bearer tokens, private client records, or sensitive shipment documents by email.