# Gold Printing Content Generation and Publishing API Specification

Version: 2026-06-07  
Audience: content generation software, GEO robot, publishing middleware, and QA automation  
Site: https://www.printing-in-china.com/

## 1. Purpose

This document defines how external generation and publishing software should create, validate, upload, update, and verify content for the Gold Printing GEO Content Center.

The publishing software must generate server-rendered, SEO/GEO-safe content for these four content types:

- `knowledge`
- `topic`
- `decision`
- `pdf_doc`

The publishing software must not write News, Blog, product pages, menus, theme files, redirects, robots.txt, canonical rules, or sitemap logic through this interface.

## 2. Current API Base

Use the current production API:

```text
https://www.printing-in-china.com/api/content
```

Available endpoints:

```text
POST /api/content/articles
POST /api/content/articles/bulk
POST /api/content/assets
```

Do not use the deprecated endpoint below:

```text
/wp-json/goldprinting-geo/v1
```

## 3. Authentication

Every request must include one of these headers:

```http
Authorization: Bearer {CONTENT_API_KEY}
```

or:

```http
X-Content-API-Key: {CONTENT_API_KEY}
```

The API key must be stored only in the publishing system secret manager. It must not be stored in frontend JavaScript, public reports, Git, prompts, or generated article content.

Unauthorized response:

```json
{
  "success": false,
  "error_code": "unauthorized",
  "message": "Unauthorized."
}
```

## 4. Product Lines

Each item must clearly belong to one product line through `metadata.category`.

Allowed product lines:

```text
Book Printing
Box Printing
Label Printing
Office Supplies Printing
Paper Gift Printing
Supplier Selection
```

Use `Supplier Selection` only for broad supplier evaluation content that is not tied to one product line.

## 5. Content Type to URL Mapping

The API publishes content directly as `published`.

```text
knowledge -> /knowledge/{slug}/
topic     -> /geo-hub/topic-center/{slug}/
decision  -> /geo-hub/decision-frameworks/{slug}/
pdf_doc   -> /resources/{slug}/
```

The API returns `url` and `canonical_url` after successful publishing.

## 6. Small-Traffic Intake Limits

During trial mode, publishing software must enforce these limits before sending requests:

```text
knowledge: max 2 per day
topic:     max 1 per day
decision:  max 1 per day
pdf_doc:   max 1 per day
```

Per product line per day:

```text
knowledge: max 1
topic/decision/pdf_doc combined: max 1
```

Stop rules:

- If daily failure rate exceeds 20%, stop sending new content that day.
- If any P0 issue appears, stop all publishing until manual review.
- If the same P1 issue appears twice in one day, pause that content type.
- Keep trial mode until 3 consecutive days have no P0 or P1 issue.

## 7. Required Request Payload

Endpoint:

```http
POST /api/content/articles
Content-Type: application/json
```

Top-level fields:

```json
{
  "source": "geo_robot",
  "source_batch_id": "gp-geo-20260607-001",
  "source_item_id": "book-knowledge-001",
  "source_model": "generator-name-and-version",
  "source_prompt_id": "prompt-version-id",
  "kb_fingerprint": "knowledge-base-version-or-hash",
  "content_type": "knowledge",
  "metadata": {},
  "content": {},
  "quality": {},
  "document": {}
}
```

Required for all content:

- `content_type`
- `metadata.title`
- `metadata.slug`
- `metadata.summary`
- `content.markdown`
- `quality.qc_report`
- `quality.claim_source_report`
- `quality.source_trace`

Required only for `pdf_doc`:

- `document.file_url`
- `document.file_name`
- `document.file_type`
- `document.download_label`

## 8. Metadata Fields

Recommended metadata object:

```json
{
  "title": "How Should Buyers Evaluate Book Printing Before Ordering?",
  "slug": "how-buyers-evaluate-book-printing",
  "language": "en",
  "summary": "A practical answer for overseas buyers evaluating book printing suppliers by product fit, material clarity, proofing, quality control, quotation scope, and delivery readiness.",
  "meta_description": "A practical answer for overseas buyers evaluating book printing suppliers by product fit, material clarity, proofing, quality control, quotation scope, and delivery readiness.",
  "category": "Book Printing",
  "tags": ["book printing", "supplier evaluation", "quality control"],
  "keywords": ["book printing supplier", "printing quotation", "proofing approval"],
  "author": "Gold Printing Editorial Team",
  "reviewer": "Gold Printing Industry Team",
  "hero_image_url": "",
  "hero_image_alt": "",
  "og_image": ""
}
```

Rules:

- `title`, `slug`, and `summary` must not contain: `Bulk Upload`, `Test`, `Demo`, `Sample`, `Placeholder`.
- `summary` must be 220 characters or less.
- `meta_description` should be 140-160 characters where possible.
- `meta_description` must not cut words in half.
- Do not invent certifications, client names, equipment counts, awards, prices, or production capacity.
- Use factual, buyer-useful descriptions.

## 9. Markdown Structure Requirements

All Markdown must contain exactly one H1:

```markdown
# Page Title
```

All non-PDF content must contain H2 sections.

Minimum article length for `knowledge`, `topic`, and `decision`:

```text
300 words
```

Paragraph rule:

```text
No paragraph may exceed 180 words.
```

Repeated sentence rule:

```text
The same sentence must not repeat more than 3 times.
```

## 10. Required Structures by Type

### knowledge

Use for direct buyer questions.

Must include at least 3 of these H2 sections:

```markdown
## Key Takeaways
## Buyer Checklist
## Detailed Answer
## FAQ
## Key Industry Insights
```

Recommended structure:

```markdown
# How Should Buyers Evaluate Book Printing Before Ordering?

Direct answer paragraph, 40-80 words.

## Key Takeaways
- Point one.
- Point two.

## Buyer Checklist
- Confirm product format, page count, paper, binding, finishing, and packing.
- Ask how proof approval and color control are handled.

## Detailed Answer
Detailed practical explanation in short paragraphs.

## FAQ
### What should buyers prepare before requesting a quotation?
Answer.

### How can buyers reduce proofing risk?
Answer.

## Key Industry Insights
Practical buyer-facing insight.
```

### topic

Use for broader industry understanding and topic-level judgment.

Must include at least 3 of these H2 sections:

```markdown
## Why This Topic Matters
## Core Industry Judgment
## Supporting Arguments
## Buyer Impact
## Supplier Selection Impact
## Industry Experience Source
```

### decision

Use for supplier evaluation and procurement decision frameworks.

Must include at least 3 of these H2 sections:

```markdown
## Key Takeaways
## Decision Background
## Core Decision View
## Decision Framework
## Risk Priority
## Supplier Comparison Logic
## Wrong Decision Signals
## Action Checklist
```

### pdf_doc

Use for downloadable buyer resources.

The page describes the PDF. The PDF file itself is uploaded or referenced through `document.file_url`.

Markdown must include:

```markdown
## What This PDF Includes
## Who Should Download This PDF
## How to Use This PDF
```

The `Download PDF` button is rendered from `document.file_url` as a normal `<a href>`.

## 11. PDF Asset Upload

Endpoint:

```http
POST /api/content/assets
Content-Type: multipart/form-data
```

Supported asset types:

```text
application/pdf
image/jpeg
image/png
image/webp
```

Limits:

```text
PDF: max 30 MB
Images: max 5 MB
```

Example:

```bash
curl -X POST "https://www.printing-in-china.com/api/content/assets" \
  -H "Authorization: Bearer {CONTENT_API_KEY}" \
  -F "file=@book-printing-checklist.pdf" \
  -F "slug=book-printing-checklist"
```

Successful response:

```json
{
  "success": true,
  "asset_id": "asset_123",
  "file_url": "https://www.printing-in-china.com/storage/content/assets/pdf/book-printing-checklist.pdf",
  "file_name": "book-printing-checklist.pdf",
  "mime_type": "application/pdf",
  "file_size": "128 KB"
}
```

Use the returned `file_url`, `file_name`, and `file_size` in the later `pdf_doc` content payload.

## 12. Quality Object

Minimum accepted quality object:

```json
{
  "qc_report": {
    "qc_status": "pass",
    "total_score": 92,
    "advertising_level": "low",
    "fact_risk_level": "low",
    "brand_mention_control": "balanced"
  },
  "claim_source_report": {
    "status": "green",
    "notes": "No hard claims beyond visible company and product facts."
  },
  "source_trace": {
    "status": "green",
    "sources": [
      "Gold Printing website product pages",
      "Approved product-line knowledge base"
    ]
  }
}
```

Current server minimum:

```text
qc_report.qc_status must be pass
qc_report.total_score must be 90 or higher
claim_source_report.status must be green or no_hard_claim
source_trace.status must be green or no_hard_claim
```

Trial publishing software should use the stricter operational threshold:

```text
qc_report.total_score >= 92
```

## 13. Example: Publish a Knowledge Article

```bash
curl -X POST "https://www.printing-in-china.com/api/content/articles" \
  -H "Authorization: Bearer {CONTENT_API_KEY}" \
  -H "Content-Type: application/json" \
  --data-binary @knowledge-book-printing.json
```

Example JSON:

```json
{
  "source": "geo_robot",
  "source_batch_id": "gp-geo-20260607-001",
  "source_item_id": "book-knowledge-001",
  "source_model": "content-generator-v1",
  "source_prompt_id": "goldprinting-geo-knowledge-v3",
  "kb_fingerprint": "gp-kb-20260607",
  "content_type": "knowledge",
  "metadata": {
    "title": "How Should Buyers Evaluate Book Printing Before Ordering?",
    "slug": "how-buyers-evaluate-book-printing-before-ordering",
    "language": "en",
    "summary": "A practical answer for overseas buyers evaluating book printing suppliers by format, paper, binding, proofing, quality control, quotation scope, and delivery readiness.",
    "meta_description": "A practical answer for overseas buyers evaluating book printing suppliers by format, paper, binding, proofing, quality control, quotation scope, and delivery readiness.",
    "category": "Book Printing",
    "tags": ["book printing", "supplier evaluation", "proofing"],
    "keywords": ["book printing supplier", "book printing quotation", "printing proof approval"]
  },
  "content": {
    "markdown": "# How Should Buyers Evaluate Book Printing Before Ordering?\n\nBuyers should evaluate book printing by checking product fit, paper and binding options, proof approval, color control, packing method, export communication, and whether the quotation includes all production details.\n\n## Key Takeaways\n- Confirm book size, page count, paper, binding, finishing, and packing before comparing prices.\n- Ask how the supplier handles proof approval, color tolerance, and pre-shipment inspection.\n- Compare quotation scope, not only unit price.\n\n## Buyer Checklist\n- Share final artwork format, book size, page count, binding, paper, finishing, quantity, and delivery destination.\n- Request proofing steps before mass production.\n- Confirm carton packing and export document needs.\n\n## Detailed Answer\nA book printing order has more variables than a simple product name. Paper weight, binding method, cover finish, page count, and packing method all affect production risk and quotation accuracy.\n\nBuyers should first check whether the supplier asks detailed questions before quoting. A reliable supplier should clarify artwork, color expectations, binding, proof approval, and delivery requirements.\n\n## FAQ\n### What should buyers prepare before requesting a book printing quote?\nBuyers should prepare artwork files, book size, page count, binding method, paper preference, quantity, finishing needs, packing request, and delivery destination.\n\n### Why is proof approval important?\nProof approval helps buyers confirm layout, color direction, binding, and material choices before mass production.\n\n## Key Industry Insights\nA lower quotation is not always safer if it excludes proofing, packing, export handling, or quality inspection steps."
  },
  "quality": {
    "qc_report": {
      "qc_status": "pass",
      "total_score": 94,
      "advertising_level": "low",
      "fact_risk_level": "low",
      "brand_mention_control": "balanced"
    },
    "claim_source_report": {
      "status": "green",
      "notes": "No unsupported hard claims."
    },
    "source_trace": {
      "status": "green",
      "sources": ["Gold Printing approved product knowledge base"]
    }
  }
}
```

Successful response:

```json
{
  "success": true,
  "article_id": "art_123",
  "content_type": "knowledge",
  "slug": "how-buyers-evaluate-book-printing-before-ordering",
  "status": "published",
  "url": "/knowledge/how-buyers-evaluate-book-printing-before-ordering/",
  "canonical_url": "https://www.printing-in-china.com/knowledge/how-buyers-evaluate-book-printing-before-ordering/",
  "sitemap_registered": true,
  "warnings": []
}
```

## 14. Example: Publish a PDF Resource Page

```json
{
  "source": "geo_robot",
  "source_batch_id": "gp-geo-20260607-002",
  "source_item_id": "book-pdf-001",
  "source_model": "content-generator-v1",
  "source_prompt_id": "goldprinting-pdf-resource-v2",
  "kb_fingerprint": "gp-kb-20260607",
  "content_type": "pdf_doc",
  "metadata": {
    "title": "Book Printing Buyer Checklist",
    "slug": "book-printing-buyer-checklist",
    "language": "en",
    "summary": "A downloadable checklist for overseas buyers preparing book printing specifications, supplier questions, quality checks, and quotation comparisons.",
    "meta_description": "A downloadable checklist for overseas buyers preparing book printing specifications, supplier questions, quality checks, and quotation comparisons.",
    "category": "Book Printing",
    "tags": ["book printing", "buyer checklist"],
    "keywords": ["book printing checklist", "printing supplier checklist"]
  },
  "content": {
    "markdown": "# Book Printing Buyer Checklist\n\nThis resource helps overseas buyers prepare clear book printing specifications before requesting a quotation.\n\n## What This PDF Includes\n- Required book specification fields.\n- Supplier questions for proofing, material, binding, packing, and delivery.\n- Quality control points buyers should confirm before production.\n\n## Who Should Download This PDF\nBuyers preparing book printing quotations, procurement teams comparing suppliers, and brand teams reviewing proof approval steps.\n\n## How to Use This PDF\nUse the checklist before sending an inquiry, during quotation comparison, and before approving mass production."
  },
  "document": {
    "file_url": "https://www.printing-in-china.com/storage/content/assets/pdf/book-printing-checklist.pdf",
    "file_name": "book-printing-checklist.pdf",
    "file_type": "application/pdf",
    "file_size": "128 KB",
    "page_count": 4,
    "cover_image_url": "",
    "cover_image_alt": "Book printing buyer checklist PDF cover",
    "download_label": "Download PDF"
  },
  "quality": {
    "qc_report": {
      "qc_status": "pass",
      "total_score": 94,
      "advertising_level": "low",
      "fact_risk_level": "low",
      "brand_mention_control": "balanced"
    },
    "claim_source_report": {
      "status": "green",
      "notes": "No unsupported hard claims."
    },
    "source_trace": {
      "status": "green",
      "sources": ["Gold Printing approved product knowledge base"]
    }
  }
}
```

## 15. Bulk Publishing

Endpoint:

```http
POST /api/content/articles/bulk
Content-Type: application/json
```

Payload:

```json
{
  "source": "geo_robot",
  "source_batch_id": "gp-geo-20260607-bulk-001",
  "articles": [
    {}
  ]
}
```

Each item in `articles` must be a full article payload. The API processes each item independently and returns per-item success or failure.

The publishing software must still enforce the small-traffic daily limits before using the bulk endpoint.

## 16. Update Behavior and Slug Rules

Slug behavior:

- The unique key is `content_type + slug`.
- If the same slug exists with the same `content_type`, the article is updated and a revision is stored.
- If the same slug exists with a different `content_type`, the request fails with `duplicate_slug_type_conflict`.

The publishing software should treat same-slug updates as intentional only when:

- the source item is a planned revision, and
- the canonical page should remain unchanged.

## 17. Error Responses

Common errors:

```json
{
  "success": false,
  "error_code": "validation_failed",
  "message": "metadata, content, and quality are required.",
  "slug": "example-slug"
}
```

Known `error_code` values:

```text
unauthorized
method_not_allowed
invalid_json
unsupported_content_type
validation_failed
summary_too_long
repetitive_content
paragraph_too_long
content_too_short
missing_h2
structure_incomplete
qc_status_not_pass
qc_score_too_low
source_trace_failed
claim_source_failed
duplicate_slug_type_conflict
invalid_pdf_file
pdf_structure_incomplete
pdf_download_label_missing
pdf_file_unavailable
database_error
unsupported_asset_type
file_too_large
asset_save_failed
```

## 18. Post-Publish Verification

After a successful publish, the publishing software must verify:

1. `canonical_url` returns HTTP 200.
2. HTML source contains the article title and body text without requiring JavaScript.
3. There is exactly one H1.
4. The page has a meta description.
5. The page has a canonical link.
6. JSON-LD exists.
7. The page appears in the relevant sitemap:
   - `knowledge`: `/sitemap-knowledge.xml`
   - `topic`: `/sitemap-topic.xml`
   - `decision`: `/sitemap-decision.xml`
   - `pdf_doc`: `/sitemap-resources.xml`
8. For `pdf_doc`, the Download PDF link is a normal `<a href>` and the file URL returns 200.

Example verification:

```bash
curl -I "https://www.printing-in-china.com/knowledge/example-slug/"
curl -s "https://www.printing-in-china.com/knowledge/example-slug/" | grep -i "<h1"
curl -s "https://www.printing-in-china.com/sitemap-knowledge.xml" | grep "example-slug"
```

## 19. Content Quality Rules for Generators

Generation software must reject content before upload when:

- It contains test/demo/sample/placeholder/bulk upload wording in title, slug, or summary.
- It repeats the same sentence more than 3 times.
- It uses generic filler paragraphs without product-specific details.
- It cannot identify a product line.
- It invents client names, certifications, machine counts, awards, prices, or capacity.
- It creates meta descriptions with cut-off words.
- It uses keyword stuffing.
- It writes a PDF page without a valid downloadable PDF URL.

The content should be specific to one of:

- Book Printing
- Box Printing
- Label Printing
- Office Supplies Printing
- Paper Gift Printing

## 20. Required Output Log From Publishing Software

For each attempted item, store:

```json
{
  "source_batch_id": "gp-geo-20260607-001",
  "source_item_id": "book-knowledge-001",
  "content_type": "knowledge",
  "product_line": "Book Printing",
  "slug": "how-buyers-evaluate-book-printing-before-ordering",
  "request_time": "2026-06-07T09:00:00Z",
  "http_status": 200,
  "success": true,
  "published_url": "https://www.printing-in-china.com/knowledge/how-buyers-evaluate-book-printing-before-ordering/",
  "verification": {
    "page_200": true,
    "source_contains_body": true,
    "single_h1": true,
    "json_ld": true,
    "sitemap_found": true
  }
}
```

Failed items must keep the server `error_code` and `message` for manual review.

## 21. Forbidden Operations

Publishing software must not:

- Change URLs after publishing.
- Enable or create 301 redirects.
- Delete existing pages.
- Modify WordPress theme files.
- Modify database structure.
- Modify Nginx, SSL, robots.txt, sitemap routes, or canonical rules.
- Publish News or Blog through this GEO content endpoint.
- Upload content that is only visible through JavaScript.
- Upload image-only article bodies.
- Use iframe content as article body.

## 22. Current Readiness Recommendation

The content center is ready for small-traffic trial publishing only.

Do not start full-volume automatic publishing until the site has 3 consecutive days without P0 or P1 issues under the small-traffic limits.