非常神奇

網站的 ui for agent 是這樣製作的

很好 可以投稿＆審核了
新增一組 api endpoint
讓我的 hermes agent 可以上網找活動、直接投稿 如何呢？

問題一、
要如何讓 hermes 知道 正確的 api format 比方說欄位、以及可接受內容
問題二、
如何避免重複投稿 是否提供一個 list all events / registrations 即可

對了 找到圖片的話 hermes 會需要 upload to imgur 我也提供一個 api 來支援嗎

給我一組 prompt 讓 coding agent 做完上述內容吧

Implement Hermes Agent Submission API

Add a small authenticated API for an external Hermes AI agent to discover the API contract, inspect existing records, and submit new events and registrations for human review.

The existing website already supports normal user submissions and admin review. Reuse the existing domain models, validation rules, enums/constants, image handling, and review workflow wherever possible. Do not create a parallel submission system unless necessary.

Before implementing, inspect the existing:

• events / event_dates
• registrations
• submission flow
• admin review flow
• validation / FormRequest classes
• sport and region constants/enums
• image storage logic
• API documentation setup
• authentication conventions

Keep the implementation simple.

Goal

Hermes should be able to:

1. Read the API specification and understand valid fields and enum values.
2. Fetch existing events and registrations to avoid duplicate submissions.
3. Submit a new event.
4. Submit a new registration.
5. Provide a remote source image URL when submitting.
6. Have the backend download and store that image using the application's existing image infrastructure.
7. Never publish content directly. All Hermes submissions must enter the existing human review workflow.

Authentication

Create a simple Bearer-token authentication mechanism suitable for one trusted internal agent.

Use environment/configuration rather than storing the token in source code.

For example:

HERMES_API_TOKEN=

Expose it through the appropriate config file.

All /api/agent/* endpoints must require this authentication.

Return standard JSON 401 responses for invalid authentication.

Do not introduce OAuth, Sanctum, API client management, or other unnecessary infrastructure unless the project already uses it and reuse is clearly simpler.

API endpoints

Implement:

GET  /api/agent/events
POST /api/agent/events

GET  /api/agent/registrations
POST /api/agent/registrations

Also make sure the existing OpenAPI/API documentation exposes these endpoints and their schemas in machine-readable form.

If the project already exposes something like:

/api/openapi.json

reuse it.

Otherwise expose the generated OpenAPI JSON in the simplest way consistent with the project's existing API documentation tooling.

GET existing records

These endpoints exist primarily so Hermes can detect previously submitted content before creating another submission.

GET /api/agent/events
GET /api/agent/registrations

Return only fields useful for duplicate detection. Do not return the complete models.

Registration should return the equivalent relevant fields.

Include both published records and records currently waiting for review so Hermes does not repeatedly submit something that is already pending.

Past records do not need to be returned if the existing application intentionally hides/removes them from active data.

For the current MVP, returning all relevant records is acceptable. Do not implement pagination, vector search, fuzzy search, embeddings, or a dedicated duplicate-check endpoint yet.

Duplicate protection

Hermes will perform semantic duplicate detection itself by inspecting the GET responses.

The server should additionally implement a cheap deterministic safety check.

At minimum, if the normalized source_url already belongs to an existing or pending record of the same domain type, reject the submission with:

409 Conflict

Example response:

{
  "message": "Possible duplicate submission.",
  "existing": {
    "public_id": "01K...",
    "title": "2026 台灣柔術公開賽"
  }
}

Normalize URLs reasonably before comparison where appropriate, for example obvious trailing-slash differences.

Do NOT build sophisticated fuzzy duplicate detection.

POST event

Implement:

POST /api/agent/events

The request schema should mirror the existing event submission/domain model.

Do not blindly use this example as the authoritative schema.

Inspect the existing Event model, user submission form, migrations, constants/enums, and validation rules first, then make the API consistent with the real application.

The OpenAPI schema must explicitly document:

• required fields
• nullable fields
• types
• date format
• valid type values
• valid sports values
• valid region values
• valid admission_type values
• examples where useful

Hermes should be able to construct a valid request from OpenAPI alone.

POST registration

Implement:

POST /api/agent/registrations

Follow the same principles.

Inspect the existing Registration model/schema and reuse its actual fields and validation.

Do not force Event-specific fields into Registration if they do not belong there.

Image ingestion

Do NOT expose Imgur or any storage-provider credentials to Hermes.

Do NOT require Hermes to upload the image separately.

The POST endpoints should accept:

thumbnail_source_url

This is the public URL of the original image discovered by Hermes.

The backend should:

thumbnail_source_url
        ↓
download image
        ↓
validate response / MIME / file size
        ↓
store using existing application image infrastructure
        ↓
save resulting thumbnail_path

If the project currently uses Imgur, keep Imgur behind this backend abstraction.

Hermes should never need to know whether images are stored on Imgur, S3, R2, local storage, etc.

Reuse existing image upload/storage services if available.

Add reasonable safeguards against bad remote image input:

• only http / https
• valid image MIME types
• reasonable maximum download size
• request timeout
• reject failed downloads
• do not trust the filename extension

Also protect the remote fetch against obvious SSRF risks: do not allow localhost, loopback, private/internal network addresses, link-local addresses, or other non-public destinations.

Avoid building a large generic media subsystem.

Review workflow

This is important:

Hermes must never be able to publish an Event or Registration.

Agent-created records must enter the same pending/draft state used by normal submissions and appear in the existing admin review interface.

The API must NOT accept fields such as:

status
published_at
approved_at

from Hermes.

Status must be determined server-side.

Reuse the existing submission/review workflow rather than creating an agent-specific review UI.

Agent attribution

If the existing submission architecture has an appropriate place to identify the submitter/source, record that the submission came from Hermes.

Prefer the smallest clean change consistent with the current architecture.

For example conceptually:

submitted_by_type = agent
submitted_by = hermes

Do not add these exact columns blindly if the current schema has a better mechanism.

The admin should ideally be able to tell that a pending submission came from Hermes.

我看 agent 提交的 就讓 user_id null 即可吧

Validation responses

Make validation errors useful to an AI client.

Use standard 422 JSON responses and expose allowed enum values where practical.

Example:

{
  "message": "Validation failed.",
  "errors": {
    "sports.0": [
      "Invalid sport. Allowed values: boxing, mma, muay_thai, kickboxing, bjj, wrestling."
    ]
  }
}

Do not maintain a second hard-coded list solely for the API. Reuse the application's authoritative constants/enums.

OpenAPI

The OpenAPI document is the authoritative machine-readable contract for Hermes.

Make sure it accurately documents:

GET  /api/agent/events
POST /api/agent/events
GET  /api/agent/registrations
POST /api/agent/registrations

including Bearer authentication.

A fresh agent reading the OpenAPI document should be able to determine:

• which endpoints exist
• authentication requirements
• request fields
• required vs optional fields
• valid enum values
• expected response formats
• validation errors
• duplicate response (409)

Avoid maintaining a separate manually duplicated Hermes schema if the existing OpenAPI tooling can derive it from application validation/schema definitions.

Tests

Add focused feature tests covering at least:

unauthenticated request → 401

authenticated GET events → 200
authenticated GET registrations → 200

valid agent event submission → pending/draft record created
valid agent registration submission → pending/draft record created

agent cannot control publication status

duplicate source_url → 409

invalid sport/region/etc → 422

remote image successfully downloaded and stored

invalid remote image → 422 or appropriate client error

private/local thumbnail URL rejected

Hermes-created submission appears in the same review workflow as normal submissions

Mock external HTTP/image requests in tests.

Keep the architecture small

This is an MVP for one trusted Hermes agent.

Do NOT add:

• embeddings
• vector databases
• fuzzy duplicate services
• queues unless already needed by existing image handling
• OAuth
• complex API client management
• separate Hermes database tables
• separate agent review system
• separate image upload endpoint
• agent publishing capability

Prefer existing application abstractions and conventions.

After implementation:

1. Run relevant tests.
2. Run formatting/static analysis used by this repository.
3. Show the final endpoint list.
4. Show an example authenticated Event POST request.
5. Show an example Registration POST request.
6. Show where Hermes can retrieve the machine-readable OpenAPI specification.
7. Briefly list files changed and any migrations/config/env variables added.