API Documentation

Overview

The guinacio.cv Agent API is a public, unauthenticated JSON API. Read endpoints have no side effects and are safe to call freely. The single write endpoint never books anything on its own: it emails the attendee a confirmation link, and only their confirmation creates the calendar event.

The machine-readable specification lives at https://guinacio.cv/openapi.json (OpenAPI 3.1, also available as YAML at /openapi.yaml). Every operation has a unique operationId, typed parameters and response schemas, so it can be loaded directly into an LLM function-calling toolchain.

Conventions

All responses are JSON with UTF-8 encoding. Timestamps are ISO-8601 with an explicit UTC offset; a datetime without an offset is rejected, because a booking must be unambiguous. Errors always carry a stable machine-readable code alongside a human message, and never arrive as an HTML page.

MCP connection details

Connect to the Model Context Protocol server at https://guinacio.cv/mcp over Streamable HTTP, protocol version 2026-07-28. No authentication is required.

Claude Code: claude mcp add --transport http guinacio-cv https://guinacio.cv/mcp

• get_profile: Name, title, about, social links, education and geographic journey.
• get_experience: Full work history: company, role, period, responsibilities and achievements.
• get_projects: Portfolio projects with tech stack, links and stars. Optional featured_only filter.
• get_skills: Technical skills by category with proficiency, years and project counts.
• get_availability: Real free calendar slots. Accepts start_date, days and duration_minutes.
• schedule_meeting (writes): Requests a free slot; the attendee receives an expiring confirmation link.

GET /api/agent/portfolio (getPortfolio)

Get the full CV: profile, experience, projects and skills

Returns everything the read tools expose in a single payload. Pure read, no side effects, no authentication. Use this when you need broad context about Guilherme in one call.

GET /api/agent/availability (getAvailability)

List real free meeting slots

Returns slots that are genuinely free on the calendar, already filtered by the booking policy: windows 18:00-24:00 and 05:00-06:00 America/Sao_Paulo, never the same local day, at least 12 hours of notice and at most 21 days ahead. Call this before scheduling and only submit a `start` value returned here.

• start_date (query, optional, string): First day to search, YYYY-MM-DD in America/Sao_Paulo. Defaults to the earliest bookable day.
• days (query, optional, integer): How many days to search from start_date. Defaults to 2; ask for more only when the user wants a wider view.
• duration_minutes (query, optional, integer): Only return slots that fit a meeting of this length. Must match what you later book.

POST /api/agent/schedule (requestMeeting)

Request a meeting (sends the attendee a confirmation email)

Validates the request and emails a signed confirmation link to the attendee. The calendar event with a Google Meet link is created ONLY after that link is opened and confirmed, within 60 minutes. Because the attendee completes the booking themselves, the email address must belong to the person actually attending. Limits: 3 requests per day per client, 3 confirmed bookings per day overall, one upcoming meeting per attendee.

• start (body, required, string): Slot start, ISO-8601 WITH an explicit UTC offset, exactly as returned by /availability.
• name (body, required, string): Attendee full name.
• email (body, required, string): Attendee email. MUST belong to the person attending: the confirmation link is sent here.
• topic (body, required, string): What the meeting is about.
• duration_minutes (body, optional, integer):

GET /api/agent (getApiIndex)

Index of this API and the other agent surfaces

Lists every endpoint with its operation id, plus links to the OpenAPI spec, docs, llms.txt and MCP endpoint.

GET /openapi.json (getOpenApiSpec)

This OpenAPI 3.1 specification

The machine-readable description of this API. Also available as YAML at /openapi.yaml.

GET /.well-known/mcp.json (getMcpManifest)

MCP server manifest

Describes the Model Context Protocol endpoint at /mcp, its transport and its tools.

Error codes

Every JSON error response carries one of the following stable codes:

• invalid_input: The request body or query parameters failed validation (bad shape, missing field, or out-of-range value).
• invalid_token: The booking confirmation token is missing, malformed, or no longer valid.
• outside_window: The requested time falls outside the booking policy: outside the allowed windows, same-day, under 12 hours notice, or beyond 21 days.
• slot_unavailable: The requested slot is no longer free on the calendar.
• duplicate_booking: The attendee already has an upcoming meeting booked.
• rate_limited: Too many requests: the per-client or per-day request limit was exceeded.
• scheduling_disabled: Meeting scheduling is temporarily disabled on the server.
• not_found: The requested resource does not exist.
• internal_error: An unexpected server error occurred while handling the request.